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Preface 



This publication is intended for the 
general CMS user. It contains information 
describing the interactive facilities of 
CMS, and includes examples showing you how 
to use CMS. 

"Part 1. Understanding CMS" contains 
sections that describe, in general terms, 
the CMS facilities and the CMS and CP 
commands that you can use to control your 
virtual machine. If you are an experienced 
programmer who has used interactive 
terminal systems before, you may be abl6 to 
refer directly to VM/370: CMS Command and 
Miicro Reference publication to find 
specific details about CMS commands that 
are summarized in this part. Otherwise, 
you may need to refer to later sections of 
this publication to gain a broader 
background in using CMS. 

The topics discussed in Part 1 are: 

• What It Means to Have a CMS Virtual 
Machine 

• VM/370-CMS Environments and Mode 
Switching 

• What You Can Do With VM/370-cnS Commands 

• The CMS File System 

• The CMS Editor 

• Introduction to the EXEC Processor 

• Using Real Printers, Punches, Headers, 
and Tapes 

"Part 2. Program Development Using CMS" 
is primarily for applications programmers 
who want to use CMS to develop and test OS 
and DOS programs under CMS. The topics 
discussed in Part 2 are: 

• Developing OS Programs Under CMS 

• Developing DOS Programs Under CMS 

• Using Access Method Services and VSAM 
Under CMS and CMS/DOS 

• How VM/370 Can Help You Debug Your 
Programs 

• Using the CMS Batch Facility 

• Programming in the CMS Environment 

"Part 3. Learning to Use EXEC" gives 
detailed information on creating EXEC 
procedures to use with CMS. The topics 
discussed in Part 3 are: 

• Building EXEC Procedures 

• Using EXECs with CMS Commands 

• Refining Your EXEC Procedures 

• Writing Edit Macros 

"Appendix A: Summary of CMS Commands" 
lists the commands available in the CMS 
command environment. 



"Appendix B: Summary of CP Commands" 
lists the CP command privilege classes and 
summarizes the commands available in the CP 
command environment. 

"Appendix C: Considerations for 3270 
Display Terminal Users" discusses aspects 
of VM/370 and CMS that are different or 
unigue when you use a 3270 display 
terminal. 

"Appendix B: Sample Terminal Sessions" 
shows sample terminal sessions for: 

• Using the CMS Editor and CMS file system 
commands 

• Using line-number editing with the CMS 
Editor 

• Creating, assembling, and executing an 
OS program in CMS 

• Creating, assembling, and executing a 
DOS program in CMS/DOS 

• Using Access Method Services in CMS 



Terminology 



Some of the following terms are used, for 
convenience, throughout this publication: 

• The term "CMS/DOS" refers to the 
functions of CMS that become available 
when you issue the command 

set dos on 

CMS/DOS is a part of the normal CMS 
system, and is not a separate system. 
Users who do not use CMS/DOS are 
sometimes referred to as OS users, since 
they use the OS simulation functions of 
CMS. 

• The term "CMS files" refers exclusively 
to files that are in the 800-byte block 
format used by CMS file system commands. 
VSAM and OS data sets and DOS files are 
not compatible with the CMS file format, 
and cannot be manipulated using CMS file 
system commands. 

• The terms "disk" and "virtual disk" are 
used interchangeably to indicate disks 
that are in your CMS virtual machine 
configuration. Where necessary, a 
distinction is made between 
CMS-formatted disks and disks in OS or 
DOS format. 



"3270" refers to both the IBM 3275 
Display Station, Model 2 and the IBM 
3277 Display Station, Model 2. 

"3330" refers to the IBM 3330 Disk 
Storage Models 1, 2, and 11, the IBM 
3333 Disk Storage and Control Models 1 
and 11, and the IBM 3350 Direct Acsess 
Storage in 3330 compatibility mode. 

"2305" refers to the IBM 2305 Fixed Head 
Storage, Models 1 and 2. 

"3340" refers to the IBM 3340 Direct 
Access Storage Facility and the IBM 3344 
Direct Access Storage. 

"3350" refers to the IBM 3350 Direct 
Access Storage device when used in 
native mode. 

Any information pertaining to the IBM 
2741 terminal also applies to the IBM 
3767 terminal, unless otherwise noted. 



Note: Information on the IBM 3344 and 3350 

Direct Access Storage Devices is for 

planning purposes only until the 
availability of the products. 

For a. glossary of VM/370 terms, see the 
III Virtual Machine Facility/370; Glossary 
and Master Index, Order Ho. GC20-1813. ~ 



E£§£eguisite Publications 



If this is the first time you have used a 
computer terminal, you should consult the 
5HZJJ5 : lii£.§.il! a 1 0ser2.s Guide, Order No. 
GC20-1810, for information on using your 
terminal. 

If your terminal is a 3767 

Communications Terminal, then IBM 3767 

OfieratorJJs Guide, Order No. GA 18-2000, Is a 
prerequisite. 

The IBM Virtual Machine F a ci 1 ity^i 20 : 
Introduction, Order No. GC20- 1800, "contains 
an overview of the VM/370 system and its 
components, and lists the programs and 
products that are supported in CMS. 



Coreguisite Publications 



111! Virtual Machine F aci li t y^3 7 : CMS 
Command and Macro Reference, Order No. 
GC20-1818, publication is a companion to 
this user's guide. It contains complete 



format descriptions of the CMS commands, 
EDIT subcommands, EXEC control statements, 
built-in functions, and special variables, 
DEBUG subcommands, and CMS assembler 
language macros that are discussed or used 
in examples in this book. 

Ill Virtual Machine Facility/37p; System 
Messages, Order No. GC20-1808, contains the 
responses, error messages, and return codes 
issued by the CMS commands, and EDIT and 
DEBUG subcommands referenced in this 
publication, as well as a complete list of 
the error messages issued by the EXEC 
processor. 

To use CMS, you should be familiar with 
the control program (CP) component of 
VM/370. The CP commands available to 
general users are described in IBM Virtual 
Ma chine Faci li t y^3 7 : CP Command Reference 
for~General UsersT Order No7 GC20-1820. If 
you are using CMS to develop programs to 
run under other operating systems, see IBM 
Virtual Machine Facility/370; Operating 
Systems in a Virtual Machine, Order No. 
GC20-1821T" 



Related VM^370 Publications 



Additional descriptions of various CMS 
functions and commands which are normally 
used by system support personnel are 
described in 

II £ Virtual Machine Fac i li ty/ 37 ; 

System Programmers Guide, Order No. 
GC20-"l807~ 

Operatorls Guide, Order No. GC20-1806 

Planning and System Generation Guide, 
Order'No. GC20-1801~ 

Interactive Problem Control System 
7lPclJ"~oierl guide 0rder~No7~GC20-1823 

lH2i£2ai§fiiSl Recording, Editing, and 
Printing (EREP) Program, Order No. 
GC 2 9- 8 3 00. 

There are two publications available as 
ready reference material when you use 
VM/370 and CMS. They are IBM Virtual 
Machine Fac i li ty^ 37 : " " 



fiuick Guide for 
GX 20- 1926 



fisers, Order No. 



Command Reference Summary, Order No. 
GX20 r "l961. 



If you are going to use the Remote 

Spooling Communications Subsystem, see the 

JBM Visual M achine £ac.ili ty./370 : Remote 

SE2°.lillS Communications Subsystem (RSCS) 
fiserIs~Guide7~0rder NoT GC20-187e>7~ 

Assembler language programmers may find 
information about the VM/370 assembler in 
QS/VS, DOS/VS, and VM/370 Assembler 
Lanaua^e, Order No. ~GC33-40To, and"" OS/VS 
and VM/370 l§§§l£i§£ P£23£M16 r i s GuideT 
Order No7~GC33-402T. 



reason codes are listed in DOS/VS Messages, 
Order No. GC33-5379. 

For a detailed description of DOS/VS 

VSAM macros and macro parameters, refer to 

the DOS/VS Supervisor and I/O Macros, Order 

No. ~GC3 3-5373. ~For~ Information on OS/VS 

VSAM macros, refer to 0,§/VS Virtual Storage 

Access Method (VSAM) ££2SE.§3i5.§rJ.s Guide, 
Order~No. GC26-38187 



Related Publications for CMS/DOS Users 



B®l5i®J Publications for VSAM anjl Access 
Method Services Users 



CMS support of Access Method Services is 
based on DOS/VS Access Method Services. The 
control statements that you can use are 
described in DOS/VS Access Method Services. 
2§££l§ Guide, Order No. GC33-5382. Error 
messages produced by the Access Method 
Services program, and return codes and 



The CMS ESERV command invokes the DOS/VS 
ESERV program, and uses, as input, the 
control statements that you would use in 
DOS/VS. These control statements are 
described in Guide to the DOS/VS Assembler, 
Order No. GC33-4024. 

Linkage editor control statements, used 
when invoking the DOS/VS linkage editor 
under CMS/DOS, are described in D0J5/VS 
S I§£®J5 C on t r ol Statements, Order No. 
GC33-53767" 
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Part 1. Understanding CMS 



Learning how to use CHS is not an end in itself: you have a specific 
task or tasks to do r and you need to use the computer to perform them. 
CMS has been designed to make these tasks easier, but if you are 
unfamiliar with CMS, then the tasks may seem more difficult. The 
information contained in Part 1 of the user's guide is organized to help 
you make the acquaintance of CMS quickly, so that it enhances, rather 
than impedes, the performance of your tasks. 

"Section 1. What It Means To Have a CMS Virtual Machine" introduces 
you to VM/370 and its conversational component, CMS. It should help you 
to get a picture of how you, at a terminal, use and interact with the 
system. 

During a terminal session, commands and requests that you enter are 

processed by different parts of the system. How and when you can 

communicate with these different programs, is described in "Section 2. 
VM/370 Environments and Mode Switching." 

There are almost two hundred commands and subcommands comprising the 
VM/370 language. There are some that you may never need to use; there 
are others that you will use over and over again. "Section 3. What You 
Can Do With VM/370-CMS Commands" contains a sampling of commands in 
various functional areas, to give you a general idea of the kinds of 
things you can do, and the commands available to help you do them. 

Almost every CMS command that you enter results in some kind of 
activity with a direct access storage device (DASD) , known in CMS simply 
as a disk, or minidisk. Data and programs are stored on disks in what 
are called "files." "Section 4. The CMS File System" introduces you to 
the creation and handling of CMS files. 

"Section 5. The CMS Editor" contains all the basic information you 
need to create and write a disk file directly from your terminal, or to 
correct or modify an existing CMS file. 

Just as important as the CMS Editor is another CMS facility, called 
the EXEC processor or interpreter. Using EXEC files, you can execute 
many commands and programs by entering a single command line from your 
terminal, or you can write your own CMS commands. "Section 6. 
Introduction to the EXEC Processor" presents a survey of the basic 
characteristics and functions of EXEC. 

"Section 7. Using Real Printers, Punches, Readers, and Tapes" 
discusses how to use punched cards and tapes in CMS, and how to use your 
virtual printer and punch to get real output. 
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Section 1. What It Means To Have a CMS Virtual Machine 



Virtual Machine Facility/370 (VM/370) is a system control program that 
controls "virtual machines." A virtual machine is the functional 
equivalent of a real computer, but where the computer has lights, 
buttons, and switches on the real console to control it, you control 
your virtual machine from your terminal, using a command language of 
active verbs and nouns. There are actually three command languages, CP, 
CMS, and RSCS. 

The command languages correspond roughly to the three components of 
VM/370: the Control Program (CP) , the Conversational Monitor System 
(CMS), the Remote Spooling Communications Subsystem (RSCS), and the 
Interactive Problem Control System (IPCS) . CP controls the resources of 
the real machine; that is, the physical machine in your computer room; 
it also manages the communications among virtual machines, and between a 
virtual machine and the real system. CMS is the conversational 
operating system designed specifically to run under CP; it can simulate 
many of the functions of the OS and DOS operating systems, so that you 
can run many OS and DOS programs in a conversational environment. RSCS 
is a subsystep designed to supervise transmission of files across a 
teleprocessing network controlled by CP. IPCS provides system 
programmers and installation support personnel with problem reporting 
and analysis functions. Its commands execute in the CMS command 
environment. 

Although this publication is concerned primarily with using CMS, it 
also contains examples of CP commands that you, as a CMS user, should be 
familiar with. 



How You Communicate with VM/370 

When you are running your virtual machine under VM/370, each command, or 
request for work, that you enter on your terminal is processed as it is 
entered; usually, you enter one command at a time and commands are 
processed in the order that you enter them. 

You can enter CP commands from either the CP or CMS environment; but 
you cannot enter CMS commands while in the CP environment. The concept 
of "environments" in VM/370 is discussed in "Section 2. VM/370 
Environments and Mode Switching." 

After you have typed or keyed in the line you wish to enter, you 
press the Return or Enter key on the keyboard. When you press this key, 
the line you have entered is passed to the command environment you want 
to have process it. If you press this key without entering any data, 
you have entered a "null line." Null lines sometimes have special 
meanings in VM/370. 

If you make a mistake entering a line, VM/370 tells you what your 
mistake was, and you must re-enter the entire command line. The 
examples in this publication assume that the command lines are correctly 
entered. 

You can enter commands using any combination of uppercase and 
lowercase characters; VM/370 translates your input to uppercase. 
Examples in this publication show all user-entered input lines in 
lowercase characters and system responses in uppercase characters. 
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?Lk§. CP Command Lancjuacje 

You use CP commands to communicate with the control program. CP commands 
control the devices attached to your virtual machine and their 
characteristics. 

For example, if you want to allocate additional disk space for a work 
area or if you want to increase the virtual address space assigned to 
your virtual machine, use the CP command DEFINE. CP takes care of the 
space allocation for you, and then allows your virtual machine to use 
it. 

Or, if for example, you are receiving printed output at your terminal 
and do not want to be interrupted by messages from other VM/370 users, 
you can use the CP command SET MSG OFF to refuse messages, since it is 
CP that handles communication among virtual machines. 

Using CP commands, you can also send messages to the VM/370 system 
operator and to other users, modify the configuration of devices in your 
virtual machine, and use the virtual machine input/output devices. CP 
commands are available to all virtual machines using VM/370. You can 
invoke these commands when you are in the virtual machine environment 
using CMS (or some other operating system) in your virtual machine. 

The CP commands and command privilege classes are listed in "Appeodix 
B: Summary of CP Commands" and are discussed in detail in the VM/370: CP 
Command Reference for General Users and VM/370: Opjjratina Systems in a 
XiEiiJisii U^chine. However, since many CP commands are used in 
conjunction with CMS commands, some of the CP commands you will use most 
frequently are discussed in this publication, in the context of their 
usefulness for a CMS application. To aid you in distinguishing between 
CMS commands and CP commands, all CP commands used in examples in this 
publication are prefaced with "CP" . 

lk§ CMS Command Lanaua^e 

The CMS command language allows you to create, modify, and debug 
problem, or application programs and, in general, to manipulate data 
files. 

Many OS language processors can be executed under CMS: the assembler, 
VS BASIC, OS FORTRAN IV, OS COBOL, and OS PL/I Optimizing and Checkout 
Compilers. In addition, the DOS/VS COBOL and DOS/VS PL/I Program 
Products are supported. You can find a comprehensive list of language 
processors that can be executed under CMS and relevant publications in 
the VM/370: Introduction. CMS executes the assembler and the compilers 
when you invoke them with CMS commands. The ASSEMBLE command is used to 
present examples in this publication; the supported compiler commands 
are described in the appropriate DOS and OS Program Product 
documentation. 

The EDIT command invokes the CMS Editor so that you can create and 
modify files. The EXEC facilities allow you to execute procedures 
consisting of CP and CMS commands; they also provide the conditional 
execution capability of a macro language. The DEBUG command gives you 
several program debugging subcommands. 

Other CMS commands allow you to read cards from a virtual card 
reader, punch cards to a virtual card punch, and print records on a 
virtual printer. Many commands are provided to help you manipulate your 
virtual disks and files. 
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Since you can invoke CP conmands from within the CMS virtual machine 
environment, the CP and CMS command languages are, for practical 
purposes, a single, integrated command language for CMS users. 

GETTING COMMANDS INTO THE SYSTEM 

Before you can use CP and CMS, you should know (1) how to operate your 
terminal and (2) your userid (user identification) and password. 

£ he Terminal: Your Virtual Console 

There are many types of terminals you can use as a VM/370 virtual 
console. Before you can conveniently use any of the commands and 
facilities described in this publication, you have to familiarize 
yourself with the terminal you are using. Generally, you can find 
information about the type of terminal you are using and how to use it 
with VM/370 in the VM/370: Terminal OserJ^s Guide. If your terminal is a 
3767, you also need the IBM 3767 Opera torJ.s Guide. 

In this publication, examples and usage notes assume that you are 
using a typewriter-style terminal (such as a 2741) . If you are using a 
display terminal (such as a 3270) , consult "Appendix C: Considerations 
for 3270 Display Terminal Users" for a discussion of special technigues 
that you can use to communicate with VM/370. 

Xou£ U§§.£il and Password: Keys into the System 

Your userid is a symbol that identifies your virtual machine to VM/370 
and allows you to gain access to the VM/370 system. Your password is a 
symbol that functions as a protective device ensuring that only those 
authorized to use your virtual machine can log on. The userid and 
password are usually defined by the system programmer for your 
installation. 

Contacting VM/370 

To establish contact with VM/370, you switch the terminal device on and 
VM/370 responds with some form of the message 

vm/370 online 

to let you know that VM/370 is running and that you can use it. If you 
do not receive the "vm/370 online" message, see the VM/370: Terminal 
User^s Guide for specific directions. You can now press the Attention 
key (or eguivalent) on your terminal and issue the LOGON command to 
identify yourself to the system: 

cp logon smith 

where SMITH represents a userid. The LOGON command is entered by 
pressing the Return (or Enter) key. If VM/370 accepts your userid, it 
responds by asking you for your password: 

ENTER PASSWORD: 

You then enter your password, which may be hidden, depending on your 
terminal. 
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LOADING CMS IN THE VIRTUAL MACHINE: THE IPL COMMAND 

You load CMS in your virtual machine using the IPL command: 

cp ipl cms 

where "cms" is assumed to be the saved system name for your 
installation's CMS. You could also load CMS by referring to it using 
its virtual device address, such as 190: 

cp ipl 190 

VM/370 responds by displaying a message such as: 

CMS VERSION v.3 - 02/28/76 12:02 

to indicate that the IPL command executed successfully and that CMS is 
loaded into your virtual machine. 

Your userid may be set up for an automatic IPL, so that you receive 
this message, indicating that you are in the CMS command environment, 
without having to issue the IPL command. 

Now you can enter a null line to begin your virtual machine 
operation. 

M2t® : !f this is the first time you are using a new virtual disk 
assigned to you, you receive the message 

DMSACC112S DISK'A(191)» DEVICE ERROR 

and you must "format" the disk, that is, prepare it for use with CMS 
files. See "Formatting Virtual Disks" below. 



Logical Line Editing Symbols 

To aid you in entering command or data lines from your terminal, VM/370 
provides a set of logical line editing symbols, which you can use to 
correct mistakes as you enter lines. Each symbol has been assigned a 
default character value. These normally are: 

Symbol Character 

Logical character delete 9 
Logical line end # 

Logical line delete t 
Logical escape " 



kSflical Character Delete 

The logical character delete symbol (d) allows you to delete one or more 
of the previous characters entered. The 3 deletes one character per 3 
entered, including the 2 and # logical editing characters. For example: 

ABC#33 results in AB 
ABC3D results in ABD 
*3DEF results in DEF 
ABC333 deletes the entire string 
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Logical Line End 

The logical line end symbol (#) allows you to key in more than one 
command on the same line, and thus minimizes the amount of time you have 
to wait between entering commands. You type the # at the end of each 
logical command line, and follow it with the next logical command line. 
VM/370 stacks the commands and executes them in seguence. For example, 
the entry 

guery blipfguery rdymsg#guery search 

is executed in the same way as the entries: 

guery blip 
guery rdymsg 
guery search 

The logical line end symbol also has special significance for the #CP 
function. Beginning any physical line with #CP indicates that you are 
entering a command that is to be processed by CP immediately. If you 
have set a character other than # as your logical line end symbol, you 
should use that character instead of a #. 



Logical Line P§i§^e 

The logical line delete symbol (£) (or [ for Teletype 1 Model 33/35 
terminals) deletes the entire previous physical line, or the last 
logical line back to (and including) the previous logical line end (#) . 
You can use it to cancel a line containing many or serious errors. If a 

# immediately precedes the £ sign, only the # sign is deleted, since the 

# indicates the beginning of a new line, and the £ cancels the current 
line. For example: 

• Logical Line Delete: 

ABC#DEF0 deletes the #DEF and results in ABC 
ABC#0 results in ABC 
ABC#DEF0#GHI results in ABCiGHI 
ABC#DEF*GHI results in ABCGHI 

• Physical Line Delete: 

ABC2 deletes the whole line 

Note that when you cancel a line by using the £ logical line delete 
symbol, you do not need to press a carriage return; you can continue 
entering data on the same line. 



* Trademark of the Teletype Corporation, Skokie, Illinois. 
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Logical Escage 

The logical escape symbol (") causes VM/370 to consider the next 
character entered to be a data character, even if it is normally one of 
the logical line editing symbols (3), £, ", or #) . For example: 

ABC"£D results in ABC2D 
""ABC" results in "ABC" 

If you enter a single logical escape symbol (") as the last character 
on a line, or on a line by itself, it is ignored. 



Defining, Logical Line Editing Symbols 

The logical line editing symbols are defined for each virtual machine 
during VM/370 system generation. If your terminal's keyboard lacks any 
of these special characters, your installation can define other special 
characters for logical line editing. You can find out what logical line 
editing symbols are in effect for your virtual machine by entering the 
command 

cp guery terminal 

The response might be something like: 

LINEND # , LINEDEL t , CHARDEL 3 , ESCAPE " 
LINESIZE 130, MASK OFF, APL OFF, ATTN OFF, MODE VM 

You can use the CP TERMINAL command to change the logical line 
editing characters for your virtual machine. For example, if you enter: 

cp terminal linend / 
Then, the line: 

input # line / input / # 

would be interpreted: 

input # line 
input 

# 

The terminal characteristics listed in the response to the CP QUERY 
TERMINAL command are all controlled by operands of the CP TERMINAL 
command. 



HOW VM/370 RESPONDS TO YOUR COMMANDS 

CP and CMS respond differently to different types of reguests. All CMS 
command responses (and all responses to CP commands that are entered 
from the CMS environment) are followed by the CMS Ready message. The 
form of the Ready message can vary, since it can be changed using the 
SET command. The long form of the Ready message is: 

R; T=7. 36/19. 89 09:26:11 
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If you have issued the command 

set rdymsg smsg 
the Ready message looks like: 

R; 

When you enter a command line incorrectly, you receive an error 
message, describing the error. The Ready message contains a return code 
from the command, for example 

R(00028) ; 

indicates that the return code from the command was 28. 

Some Samjale CP and CMS Command Responses 

If you enter a CP or CMS command that reguests information about your 
virtual machine, the response should be the information reguested. For 
example, if you issue the command 

cp display g 

CP responds by showing you the contents of your virtual machine's 
general registers, for example: 

GPR = 00000003 00003340 000007A0 00000003 

GPR 4 = 00000848 C4404040 00000040 00002DF0 

GPR 8 = 00000008 000132F8 00002BA0 00002230 

GPR 12 = 00003238 FFFFFFFD 50013386 00000000 

Similarly, if you issue the CMS command 

listfile * assemble c 

you might receive the following information: 

JUNK ASSEMBLE C1 
MYPROG ASSEMBLE C1 

If you enter a CP command to alter your virtual machine configuration 
or the status of your spool files, CP responds by telling you that the 
task is accomplished. The response to 

cp purge reader all 

might be 

0004 FILES PURGED 

Some CP commands, those that alter some of the characteristics of 
your virtual machine, give you no response at all. If you enter 

cp spool e class x hold 

you receive no response from CP. 

Certain CMS commands may issue prompting messages, to reguest you to 
enter more information. The SORT command, which sorts CMS disk files, 
is an example. If you enter: 

sort in file a1 out file a1 
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you are prompted with the message: 

DMSSRT604R ENTER SORT FIELDS: 

and you can then specify which fields you wish the input records to be 
sorted on. 



Getting Acquainted with CMS 

If you have just logged on for the first time, and you want to try a few 
CMS commands, enter: 

query disk a 

The response should tell you that you have an A-disk at virtual address 
191; it also provides information such as how much room there is on the 
disk and how much of it is used. Again, if you receive an error message 
that indicates the disk may not be formatted, see "Formatting Virtual 
Disks." 

Your A-disk is the disk you use most often in CMS, to contain your 
CMS files. Files are collections of data, and may have many purposes. 
For this exercise, the data is meaningless. Enter 

edit junk file 

You should receive the response 

NEW FILE: 
EDIT: 

which indicates that this file does not already exist on your A-disk. 
Enter: 

input 

You should receive the response: 

INPUT: 

and you can start to create the file, that is, write input records that 
are eventually going to be written onto your A-disk. Enter 5 or 6 data 
lines, such as 

hickory dickory dock 
the mouse ran up the clock 
the clock struck one 
and down he run 
dickory hickory dock 

Now, enter a null line (one with no data) . You should receive the 
message 

EDIT: 
Enter 

file 
You should see the message 

R; T=0.01/0.02 19:31:29 

20 IBM VM/370: CMS User's Guide 



You have just written a CMS file onto your A-disk. If you enter: 

type junk file a 

you should see the following: 

HICKORY DICKORY DOCK 

THE MOUSE RAN UP THE CLOCK 

THE CLOCK STRUCK ONE 

AND DOWN HE RUN 

DICKORY HICKORY DOCK 

The CMS command, TYPE, requested a display of the disk file JUNK FILE, 
on your A-disk. 

To erase the file, enter 

erase junk file 

Now, if you re-enter the TYPE command, you should receive the message 

FILE NOT FOUND 

Most CMS commands create or reference disk files, and are as easy to 
use as the commands shown above. Your CMS disks are among the most 
important features in your VM/370 virtual machine. 



Virtual Disks and How They Are Defined 

Under VM/370, a real direct access storage device (DASD) unit, or disk 
pack, can be divided into many small areas, called minidisks. Minidisks 
(also called virtual disks because they are not equivalent to an entire 
real disk) are defined in the VM/370 directory, as extents on real 
disks. For CMS applications, you never have to be concerned with the 
extents on your minidisks; when you use CMS- formatted minidisks, they 
are, for practical purposes, functionally the same as real disks. 
Minidisks can also be formatted for use with OS or DOS data sets or VSAM 
files. 

You can have both permanent and temporary disks attached to your 
machine during a terminal session. Permanent disks are defined in the 
VM/370 directory entry for your virtual machine. Temporary disks are 
those you define for your own virtual machine using the CP DEFINE 
command, or those attached to your virtual machine by the system 
operator. 



PERMANENT VIRTUAL DISKS 

The VM/370 directory entry for your userid defines your permanent 
virtual disks. Each disk has associated with it an access mode 
specifying whether you can read and write on the disk or only read from 
it (its read/write status). Virtual disk entries in the VM/370 
directory may look like the following: 



MDISK 


190 


2314 


000 


050 


CMS190 


R 


MDISK 


191 


3330 


010 


005 


BDISKE 


H 


MDISK 


194 


3330 


010 


020 


CMS001 


W 


MDISK 


198 


3330 


050 


010 


CMS192 


w 


MDISK 


19E 


3330 


010 


050 


CMS19E 


R 
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The first two fields describe the device, minidisk in this example, 
and the virtual address of the device. Virtual addresses (shown above 
as 190, 191, and so on), are the names by which you and VM/370 identify 
the disk. Each device in your virtual machine has an address which may 
or may not correspond to the actual location of the device on the VM/370 
system. 

The third field specifies the device type of your virtual disk. The 
fourth and fifth fields specify the starting real cylinder at which your 
virtual disk logically begins and the number of cylinders allocated to 
your virtual disk, respectively. The sixth field is the label of the 
real disk on which the virtual disk is defined and the seventh field is 
a letter specifying the read/write mode of the disk; "R" indicates that 
the disk is a read-only disk, and "W" indicates that you have read/write 
privileges. The MDISK control statement of the Directory Service 
Program is described in the VM/370: O^erator^s Guide. 



DEFINING TEMPORARY VIRTUAL DISKS 

Using the CP DEFINE command, you can attach a temporary disk to your 
virtual machine for the duration of a terminal session. The following 
command allocates a 10-cylinder temporary disk from a 3330 device and 
assigns it a virtual address of 291: 

cp define t3330 as 291 cyl 10 

When you define a minidisk, you can choose any valid address that is not 
already assigned to a device in your virtual machine. Valid addresses 
for minidisks range from 001 through 5FF, for a virtual machine in basic 
control mode. 



FORMATTING VIRTUAL DISKS 

Before you can use any new virtual disk, you must format it. This 
applies to new disks that have been assigned to you and to temporary 
disks that you have allocated with the CP DEFINE command. When you 
issue the FORMAT command you must use the virtual address you have 
defined for the disk and assign a CMS mode letter, for example: 

format 291 c 

CMS then prompts you with the following message: 

DMSFOR603R FORMAT HILL ERASE ALL FILES ON DISK •C(291)«. DO YOU 
WISH TO CONTINUE? (YES|N0): 

You respond: 

yes 

CMS then asks you to assign a label for the disk, which may be anything 
you choose. Labels can have a maximum of 6 characters. When the 

DMSFOR605R ENTER DISK LABEL: 

message is issued, you respond by supplying a disk label. For example, 
if this is a temporary disk, you might enter 

scrtch 
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CHS then erases all the files on that disk, if any existed, and formats 
the disk for your use. When you enter the label, CMS responds by 
telling you: 

FORMATTING DISK 'C 

•10' CYLINDERS FORMATTED ON »C(291)'. 

R; T=0. 15/1.60 11:26:03 

The FORMAT command should only be used to format CMS disks, that is, 
disks you are going to use to contain CMS files. If you want to format 
disks for OS, DOS, or VSAN applications, the disks should be formatted 
using the IBCDASDI program. 



Sharing Virtual Disks: Linking 

Since only one user can own a virtual disk, and there are many occasions 
that require users to share data or programs, VM/370 allows you to share 
virtual disks, on either a permanent or temporary basis, by "linking." 

Permanent links can be established for you in your VM/370 directory 
entry. These disks are then a part of your virtual machine 
configuration every time you log on. 

You can also have another user's disk temporarily added to your 
configuration by using the CP LINK command. For example, if you have a 
program that uses data that resides on a disk identified in userid 
DATA'S configuration as a 194, and you know that the password assigned 
to this disk is GO, you could issue the command 

cp link to data 194 as 198 r pass= go 

DATA'S 194 disk is then added to your virtual machine configuration at 
virtual address 198. 

The "R" in the command line indicates the access mode; in this case, 
it tells CP that you wish only to read files from this disk. VM/370 
will not allow you to write on it. If you try to issue this command 
when someone is logged on to the userid DATA, you will not be able to 
establish the link. If you want to link to DATA in any event, you can 
reissue the LINK command using the access mode RR: 

cp link data 194 198 rr go 

The keywords TO, AS, and PASS= are optional; you do not have to specify 
them. 

You can also use the CP LINK command to link to your own disks. For 
example, if you log on and discover that another user has access to one 
of your disks, you may be given read-only access, even if it is a 
read/write disk. You can request the other user to detach your disk 
from his virtual machine, and after he has done so, you can establish 
the link: 

cp link * 191 191 

Hhen you link to your own disks, you can specify the userid as * and you 
do not need to specify the access mode or a password. 
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You can find more information about the CP LINK command and CP access 
modes in VH/370: CP Command Reference for General Users. 



Identifying Your Disk to CMS: Accessing 

LINK and DEFINE are CP commands: they tell CP to add DASD devices to 
your virtual machine configuration. CMS must also know about these 
disks, and you must use the ACCESS command to establish a filemode 
letter for them: 

access 194 b 

CHS uses filemode letters to manage your files during a terminal 
session. By using the ACCESS command you can control: 

• Whether you can write on a disk or only read from it (its read/write 
status) . 

• The library search order for programs executing in your virtual 
machine. 

• Which disks are to contain the new files that you create. 

If you want to know which disks you currently have access to, issue 
the command 

guery search 

you might see the following display: 

PER191 191 A R/W 

DAT194 198 B R/0 

CMS190 190 S R/O 

CHS19E 19E Y R/O 

The first column indicates the label on the disk (assigned when the disk 
is formatted) , and the second column shows the virtual address assigned 
to it. 

The third column contains the filemode letter. Valid filemode letters 
are A, B, C, D, E, F, 6, S, Y, and Z. 

The fourth column indicates the read/write status of the disk. The 
190 and 19E disks in this example are read-only disks that contain the 
CMS nucleus and disk-resident commands for the CNS system. 

For the most part you will probably use your 191 disk, that is, your 
A-disk. 



RELEASING VIRTUAL DISKS 

When you no longer need a disk during a terminal session, or if you want 
to assign a currently active filemode letter to another disk, use the 
CHS command RELEASE: 

release c 

Then, you can issue the ACCESS command to assign the filemode letter C 
to another disk. 
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When you no longer need disks in your virtual machine configuration, 
use the CP command DETACH to disconnect them from your virtual machine: 

cp detach 194 
cp detach 291 

If you are going to release and detach the disk at the same time, you 
can use the DET option of the RELEASE command: 

release 194 (det 

For more information on controlling disks in CMS, see "Section 4. The 
CMS File System." 
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Section 2. VM/370 Environments and Mode Switching 



When you are using VM/370, your virtual machine can be in one of two 
possible "environments": the CP r or control program environment, or the 
virtual machine environment, which may be CMS. The CMS environment has 
several subenvironments, sometimes called "modes." Each environment or 
subenvironment accepts particular commands or subcommands, and each 
environment has its own entry and exit paths, responses and error 
messages. If you have a good understanding of how the VM/370 
environments are related, you can learn to change environments guickly 
and use your virtual machine efficiently. 

This section introduces the CP and CMS environments that you use and 
describes: 

• Entry and exit paths 

• Command subsets that are valid as input 

Figure 1 , at the end of this section, summarizes the VM/370 command 
environments and lists the commands and terminal paths that allow you to 
go from one environment to another. 

With the exception of input mode in the edit environment, you can 
always determine which environment your virtual machine is in by 
pressing the Return or Enter key on a null line. The responses you 
receive, and the environments they indicate, are: 

Iesp_onse Environment 

CP CP 

CMS CMS 

CMS (DOS ON) CMS/DOS 

EDIT: Edit 

CMS SUBSET CMS Subset 

DEBUG Debug 



The CP Environment 

When you log on to VM/370, your virtual machine is in the CP 
environment. In this environment, you can enter any CP command that is 
valid for your privilege class. This publication assumes that you are a 
general, or class G, user. You can find information about the commands 
that you can use in the VM/370: CP Command Reference for General Users. 

Only CP commands are valid terminal input in the CP environment. You 
can, however, preface a CP command line with the characters "CP" or 
"#CP", followed by one or more blanks, although it is not necessary. 
These functions are described under "The CMS Environment." 

You can enter CP commands from other VM/370 environments. There may 
be times during your terminal session when you want to enter the CP 
environment to issue one or more CP commands. You can do this from any 
other environment by doing either of two things: 

1 . Issue the command 

#cp 
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2. Use your terminal's Attention key (or equivalent). On a 2741 
terminal, you must normally press the Attention key twice, quickly, 
to enter the CP environment. 

The following message indicates that your virtual machine is in the CP 
environment: 

CP 

After entering whatever CP commands you need to use, you return your 
virtual machine to the environment or mode that it came from by using 
the CP command 

cp begin 

which, literally, begins execution of your virtual machine. 



The CMS Environment 

You enter the CMS environment from CP by issuing the IPL command, which 
loads CMS into your virtual storage area. If you are planning to use 
CMS for your entire terminal session, you should not have to IPL again 
unless a program failure forces you into the CP environment. 

When you issue the IPL command, you can specify either the named 
system CMS at your installation or you can load CMS by specifying the 
virtual address of the disk on which the CMS system resides. For 
example, 

cp ipl cms 

— or — 

cp ipl 190 

When your virtual machine is in the CMS environment, you can issue 
any CMS command and any of the CP commands that are valid for your user 
privilege class. You can also execute many of your own OS or DOS 
programs; the ways you can execute programs are discussed in "Section 8. 
Developing OS Programs Under CMS" and "Section 9. Developing DOS 
Programs Under CMS." 

You can enter CP commands from CMS in any of the following ways: 

« Using the implied CP function of CMS (See Note.) 
» With the CP command 
« With the #CP function 

Il2l® : For tne nost part, you may enter any CP command directly from the 
CMS environment. This implied CP function is controlled by an operand 
of the CMS SET command, IMPCP. You can determine whether the implied CP 
function is in effect for your virtual machine by entering the command 

query impcp 
If the response is 

IMPCP = OFF 
you can change it, by entering 

set impcp on 
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When the implied CP function is set off, you must use either the CP 
command or the #CP function to enter CP commands from the CMS 
environment. CP commands that you execute in EXEC procedures must 
always be prefaced by the CP command, regardless of the implied CP 
setting. An example of using the CP command is: 

cp close punch 

When you issue CP commands from the CMS environment either implicitly 
or with the CP command, you receive, in addition to the CP response (if 
any) , the CMS Ready message. If you use the #CP function, discussed 
next, you do not receive the Ready message. 

You can preface any CP command line with the characters "#CP", 
followed by one or more blanks. When you enter a CP command this way, 
the command is processed by CP immediately; it is as if your virtual 
machine were actually in the CP environment. 



EDIT, INPUT, AND CMS SUBSET 

The CMS Editor is a VM/370 facility that allows you to create and modify 
data files that reside on CMS disks. The editor environment, more 
commonly called the edit environment, is entered when you issue the CMS 
command EDIT, specifying the identification of a data file you want to 
create or modify. 

edit myfile assemble 

is an example of how you would enter the edit environment to either 
create a file called MYFILE ASSEMBLE or to make changes to a disk file 
that already exists under that name. 

When you enter the edit environment your virtual machine is 
automatically in edit mode, where you can only issue EDIT subcommands or 
CP commands prefaced by "#CP." EDIT subcommands tell the editor what 
you wish to do with the data you have accessed. After you enter the 
EDIT subcommand 

input 

data lines that you enter are considered input to the file. To return 
to edit mode, you must enter a null line. 

If you issue the EDIT subcommand 

cms 

the editor responds 

CMS SUBSET 

and your virtual machine is in CMS subset mode, where you can issue any 
valid CMS subset command, that is, a CMS command that is allowed in CMS 
subset mode. These include: 

ACCESS 

CP 

DISK 

ERASE 

EXEC 

HT 
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LISTFILE 


RT 


PRINT 


SET 


PUNCH 


STATE 


QUERY 


STATEW 


READCARD 


TYPE 



You can also issue CP commands. To return to edit mode, you use the 

special CMS subset command, RETURN. If you enter the Immediate command 

HX, your editing session is terminated abnormally and your virtual 
machine is returned to the CMS environment. 

When you are finished with an edit session, you return to the CMS 
environment by issuing the FILE subcommand, which indicates that all 
modifications or data insertions that you have made should be written 
onto a CMS disk, or by issuing the subcommand QOIT, which tells the 
editor not to save any modifications or insertions made since the last 
time the file was written. 

More detailed information about EDIT subcommands and how to use the 
CMS Editor is contained in this publication in "Section 5. The CMS 
Editor" and in the VM/370: CMS Command and Macro Reference. 



DEBUG 

CMS DEBUG is a special CMS facility that provides subcommands to help 
you debug programs at your terminal. Your virtual machine enters the 
debug environment when you issue the CMS command 

debug 

You may want to enter this command after you have loaded a program into 
storage and before you begin executing it. At this time you can set 
"breakpoints," or address stops, where you wish to halt your program's 
execution so that you can examine and change the contents of general 
registers and storage areas. When these breakpoints are encountered, 
your virtual machine is placed in the debug environment. You can also 
enter the debug environment by issuing the CP EXTERNAL command, which 
causes an external interrupt to your virtual machine. 

Valid DEBUG subcommands that you can enter in this environment are: 

BREAK GO RETURN 

CAW GPR SET 

CSW HX STORE 

DEFINE ORIGIN X 

DUMP PSH 

You can also use the #CP function in the debug environment to enter CP 
commands. 

You leave the debug environment in any of the following ways: 

«> If the program you are running completes execution, you are returned 
to the CMS environment. 

•> if your virtual machine entered the debug environment after a 
breakpoint was encountered, it returns to CMS when you issue the 
DEBUG subcommand 

hx 

To continue the execution of your program, you use the DEBUG 
subcommand 

go 
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If your virtual machine is in the debug environment and is not 
executing a program, the DEBUG subcommand 

return 

returns it to the CMS environment. 



CMS/DOS 

If you are a DOS/VS user, the CMS/DOS environment provides you with all 
the CMS interactive functions and facilities, as well as special s CMS/DOS 
commands which simulate DOS functions. The CMS/DOS environment becomes 
active when you issue the command 

set dos on 

When your virtual machine is in the CMS/DOS environment you can issue 
any command line that would be valid in the CMS environment, including 
the facilities of EDIT, DEBUG, and EXEC, but excluding CMS commands or 
program modules that load and/or execute programs that use OS macros or 
functions. 

The following commands are provided in CMS/DOS to test and develop 
DOS programs, and to provide access to DOS/VS libraries: 

ASSGN DSERV OPTION 

DLBL ESERV PSERV 

DOSLIB FETCH RSERV 

DOSLKED FCOBOL SSERV 

DOSPLI LISTIO 

Your virtual machine leaves the CMS/DOS environment when you issue the 
command 

set dos off 

If you reload CMS (with an IPL command) during a terminal session, you 
must also reissue the SET DOS ON command. 



Interrupting Program Execution 

When you are executing a program under CMS or executing a CMS command, 
your virtual machine is not available for you to enter commands. There 
are, however, ways in which you can interrupt a program and halt its 
execution, either temporarily, in which case you can resume its 
execution, or permanently, in which case your virtual machine returns to 
the CMS environment. In both cases, you interrupt execution by creating 
an "attention interrupt," which may take two forms: 

• An attention interrupt to your virtual machine operating system 

• An attention interrupt to the control program 

These situations result in what are known as virtual machine (VM) or 
control program (CP) "reads" being presented to your virtual console. 
On a typewriter terminal, the keyboard unlocks when a read occurs. 

Whether you have to press the Attention key once or twice depends on 
the terminal mode setting in effect for your virtual machine. This 
setting is controlled by the CP TERMINAL command: 
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cp terminal mode vm 

The setting VM is the default for virtual machines; you do not need to 
specify it. The VM setting indicates that one depression of the 
Attention key sends an interrupt to your virtual machine, and that two 
depressions results in an interrupt to the control program (CP) . 

The CP setting for terminal mode, which is the default for the system 
operator, indicates that one depression of the Attention key results in 
an interrupt to the control program (CP) . If you are using your virtual 
■achine to run an operating system other than CMS, you might wish to use 
this setting, also. Issue the command: 

cp terminal mode cp 



VIRTUAL MACHINE INTERRUPTS 



While a command or program is executing, if you press the Attention key 
once on a 2741 (or the Enter key on a 3270), you have created a virtual 
machine interrupt. The program halts execution, your terminal will 
accept an input line, and you may: 

* Terminate the execution of the program, by issuing an Immediate 
command to halt execution : 

hx 

The HX command causes the program to abnormally terminate (abend) . 

« Enter a CMS command. The command is stacked in a console buffer and 
is processed by CMS when your program is finished executing and the 
next virtual machine read occurs. For example: 

print abc listing 

After you enter this line, the program resumes execution. 

«» If the program is directing output to your terminal and you wish only 
to halt the terminal display, use the Immediate command: 

ht 

The program resumes execution. You can, if you want, cause another 
interrupt and reguest that typing be resumed by entering the RT 
(resume typing) command: 

rt 

« Enter a null line; your program continues execution. The null line is 
stacked in the console stack and read by CMS as a stacked command 
line. 

HX, HT, and RT are three of the CMS Immediate commands. They are 
"immediate" because they are executed as soon as they are entered. 
Unlike other commands, they are not stacked in the console buffer. You 
can only enter an Immediate command following an attention interrupt. 
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CONTROL PROGRAM INTERRUPTS 

You can interrupt a program and enter the CP environment directly by 
pressing the Attention key twice guickly, on a 274 1 r or pressing the PA 1 
key on a 3270. Then, you can enter any CP command. To resume the 
program*s execution, issue the CP command: 

cp begin 

If your terminal is operating with the terminal mode set to CP, pressing 
the Attention key once places your virtual machine in the CP 
environment. 



ADDRESS STOPS AND BREAKPOINTS 

A program may also be interrupted by an instruction address stop, which 
you specifically set by the CP command ADSTOP. For example, if you 
issue the command 

cp adstop 201ea 

An address stop is set at virtual storage location X^OIEA'. When your 
program reaches this address during its execution, it is interrupted and 
your virtual machine is placed in the CP environment, where you can 
issue any CP command, including another ADSTOP command, before resuming 
your program*s execution with the CP command BEGIN. 

Breakpoints, similar to address stops, are set using the DEBUG 
subcommand BREAK, which you issue in the debug environment before 
executing a program. For example, if you issue: 

break 1 201ae 

Your program's execution is interrupted at this address and your virtual 
machine is placed in the debug environment. You can then enter any 
DEBUG subcommand. To resume program execution, use the DEBUG subcommand 
GO. If you want to halt execution of the program entirely, use the 
DEBUG subcommand HX, which returns your virtual machine to the CMS 
environment. You can find more information about setting address stops 
and breakpoints in "Section 11. How VM/370 Can Help You Debug Your 
Programs. " 
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Any time that a CP command can be entered, it may be prefaced with #CP. 

'The BEGIN command returns your virtual machine to the environment it was in 
when CP was entered: 

*lf you were in edit or input mode, the current line pointer remains unchanged. 

*lf you were executing a program, execution resumes at the instruction address 
indicated in the PSW. 
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Section 3. What You Can Do With VM/370-CMS Commands 



This section provides an overview of the CMS and CP command languages, 
and describes the various commands within functional areas, with 
examples. The commands are not presented in their entirety, nor is a 
complete selection of commands represented. 

When you finish reading this section you should have an understanding 
for the kinds of commands available to you, so that when you need to 
perform a particular task using CMS you may have an idea of whether it 
can be done, and know what command to reference for details. For 
complete lists of the CP and CMS commands available in the VM/370 
system, see "Appendix A: summary of CMS Commands" and "Appendix B: 
Summary of CP Commands." 



Command Defaults 

Many of the characteristics of your CMS virtual machine are already 
established when you log on, but there are commands available so you can 
change them. In the case of many CMS commands, there are implied values 
for operands, so that when you enter a command line without certain 
operands, values are assumed for them. In both of these instances, the 
values set or implied are considered default values. As you learn CP 
and CMS commands, you also should become familiar with the default 
values or settings for each. 



Commands To Control Terminal Communications 

Using VM/370, you control your virtual machine directly frcm your 
terminal. VM/370 provides a complement of commands for terminal 
communications. 



ESTABLISHING AND TERMINATING COMMUNICATIONS WITH VM/370 

To initiate your communication with VM/370, use the CP LOGON command: 

cp logon sam 
Optionally, you may enter your password on the same line: 

cp logon sam 123456 

When you are sure that your communication line is all right and you have 
difficulty logging on (for example, someone else has logged on under 
your userid) , you can use the CP MESSAGE command: 

cp message sam this is sam.. .pis log off 

Another way to access the VM/370 system is to use the CP command 
DIAL: 

cp dial tsosys 
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In this example, TSOSYS is the userid of a virtual machine running a TSO 
system. After this DIAL command is successful, you can use your 
terminal as if you were actually connected to a TSO system, and you can 
begin TSO logon procedures. 

To end your terminal session, use the CP command LOGOFF: 

cp logoff 

If you have used a switched (or dial-up) communication path to the 
VM/370 computer and you want the line to remain available, you can 
enter: 

cp logoff hold 

At times, you might be running a long program under one userid and wish 
to use your terminal for some other work. Then, you can disconnect your 
terminal : 

cp disconn 

— or — 

cp disconn hold 

Your virtual machine continues to run, and is logged off the system when 
your program has finished executing. If you want to regain terminal 
control of your virtual machine after disconnecting, log on as you would 
to initiate your terminal session. Your virtual machine is placed in 
the CP environment, and to resume its execution, you use the CP command 
BEGIN. 

You should not disconnect your virtual machine if a program requires 
an operator response, since the console read request cannot be 
satisfied . 



CONTROLLING WHAT YOU RECEIVE AT YOUR TERMINAL 

During the course of a terminal session, you can receive many kinds of 
messages from VM/370, from the system operator, from other users, or 
from your own programs. You can decide whether or not you want these 
messages to actually reach you. For example* if you use the command 

cp set msg off 

No one will be able to send messages to you with the CP MESSAGE command; 
if another virtual machine user tries to send you a message, he receives 
a message 

userid NOT RECEIVING, MSG OFF 

Similarly, you can use 

cp set wng off 

to prevent warning messages (which usually come from the system 
operator) from coming to you. You would probably do this, however, only 
in cases where you were typing some output at your terminal and did not 
want the copy ruined. 

VM/370 issues error messages whenever you issue a command incorrectly 
or if a command or program fails. These messages have a long form, 
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consisting of the error message code and number, followed by text 
describing the error. If you wish to receive only the text portion of 
messages with severity codes I, E, and W (for Informational, Error, and 
Warning, respectively), you can issue the command: 

cp set emsg text 

If you want to receive only the message code and number, (from which you 
can locate an explanation of the error in VMZJ29. : System Messages) you 
specify 

cp set emsg code 

You can also cancel error messages completely: 

cp set emsg off 

To restore the EMSG setting to its default, which is the message code 
and text, enter: 

cp set emsg on 

Some CP commands issue informational messages telling you that CP has 
performed a particular function. You can prevent the reception of these 
messages with the command 

cp set imsg off 
or restore the default by issuing 

cp set imsg on 

The setting of EMSG applies to CHS commands as well as to CP commands. 

You can also control the format of the CMS Ready message. If you 
enter 

set rdymsg smsg 

you receive only the "R;" or shortened form of the Beady message after 
the completion of CMS commands. If you are not receiving error messages 
(as described above) and an error occurs, the return code from the 
command still appears in parentheses following the "R" . 

An additional feature exists for CMS. If you have a typewriter 
terminal with a two-color ribbon, you can specify 

set redtype on 

so that CMS error messages are typed in red. 

Some commands or messages result in displays of lines that are very 

long. If you want to limit the width of lines that are received at your 

terminal (for example, if you are using terminal paper that is only 
eight inches wide), you can specify: 

cp terminal linesize 80 

so that all lines received at your terminal are formatted to fit within 
an 80-character display. 

You can also control two special characters in VM/370. One is the 
exclamation point (!) that types when the Attention key is pressed. If 
you do not want this character to type when you press the Attention key, 
use the command: 
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cp terminal attn off 

CMS allows you to specify a "blip" character: this character is typed 
or displayed whenever two seconds of CPU time are used. If you enter 

set blip * 

then, when a program is executing, this character types for every two 
seconds of CPU time. You can cancel the function: 

set blip off 

or set it to nonprintable characters: 

set blip on 

When this command has been entered on a typewriter terminal, the 
selectric type ball tilts and rotates whenever a blip character is 
expected. 



COMMANDS TO CONTROL HOW VM/370 PROCESSES INPUT LINES 

You can manipulate VM/OVO^ logical line editing function to suit your 
own needs. In addition to using the CP TERMINAL command to change the 
default logical line editing symbols, you can issue 

cp set linedit off 

so that none of the symbols are recognized by VM/370 when it interprets 
your input lines. 

When you are in the CMS environment, there are a number of commands 
that you can use to control how CMS validates a command line. The SET 
command functions IMPCP (implied CP) and IMPEX (implied EXEC) control 
the recognition of CP commands and CMS EXEC procedures. For example, if 
you issue 

set impcp off # set impex off 

then, when you enter CP commands in CMS or try to execute EXEC 
procedures, you must preface the name of the command or procedure with 
CP (or #CP) , or EXEC, respectively. If implied EXEC is set to off, you 
cannot use edit macros. 

By using the SYNONYM and the SET ABBREV commands, you can control 
what command names, synonyms, or truncations are valid in CMS. For 
example, you could set up a file named MYSYN SYNONYM which contains the 
following records: 

PRINT PRT 1 

RELEASE LETGOOF 5 

ACCESS GET 1 

DOSLKED LNKEDT 3 

The first column specifies an existing CMS command, module, or EXEC 
name; the second column specifies the alternate name, or synonym, you 
want to use; and the third column is a count field that indicates the 
minimum number of characters of the synonym that can be used to truncate 
the name. Using this file, after you enter the command 

synonym mysyn 
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you can use PRT, LETGOOF, GET, and LNKEDT in place of the corresponding 
CMS command names. Also, if the ABBREV function is in effect, (it is 
the default; you can make sure it is in effect by issuing the command 
SET ABBREV ON) , you can truncate any of your synonyms to the minimum 
number of characters specified in the count field of the record (that 
is, you could enter "p" for PRINT, "letgo" for RELEASE, and so on). 

You can set up EXEC files with the same names as CMS commands, that 
may or may not perform the same function as the CMS names they 
duplicate. For example, if every time you used the GLOBAL command you 
used the same operands, you could have an EXEC file, named GLOBAL, that 
contained a single record: 

global maclib cmslib osmacro 
Then, every time you entered the command name 

global 

the command GLOBAL MACLIB CMSLIB OSMACRO would execute. 

As another example, suppose you had an EXEC file named •T 1 , that 
contained the following records: 

&CONTROL OFF 
CP QUERY TIME 

Then, whenever you entered 

t 

you would receive the CP time-of-day message, and you could no longer 
use the truncation "T" for the CMS command TYPE. In order to see the 
contents of a CMS file displayed at your terminal you would have to 
enter at least "TY" as a truncation. 



CONTROLLING KEYBOARD-DEPENDENT COMMUNICATIONS 

You are dependent on your terminal for communication with VM/370: when 
your virtual machine is waiting for a read either from the control 
program or from your virtual machine operating system, you can not 
receive messages until you press the Return key to enter a command or a 
null line. If you are in a situation where you must wait for a message 
before continuing your work, for example, if you are waiting for a tape 
device to be attached to your virtual machine, you can use the CP 
command SLEEP to lock your keyboard: 

cp sleep 

You must then press the Attention key to get out of sleep and unlock the 
keyboard so you can enter a command. 

If your virtual machine is in the CP environnent when you issue the 
SLEEP command, or if you issue the SLEEP command from the CMS 
environment using the #CP function, your virtual machine is in the CP 
environment after you press the Attention key. If your virtual machine 
is in the CMS environment when you enter the SLEEP command (or if you 
enter CP SLEEP) , your virtual machine is in the CMS environment when you 
press the Attention key once. 

You can control the effect of pressing the Attention key or your 
terminal with the CP TERMINAL command. If you specify: 
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cp terminal mode cp 

then, whenever you press the Attention key, you are in the CP 
environment. 

If you use the default terminal mode setting, which is VH, and then 
you press the Attention key once, you cause a read to your virtual 
machine; if you press the Attention key twice you cause a CP read, and 
you are in the CP environment. 

The effect of pressing the Attention key is also important when you 
are executing a program. At times, you may wish to enter some CP 
commands while your program executes, but you do not want to interrupt 
the execution of the program. If, before you begin your program you 
issue the command 

cp set run on 

and then use the Attention key to get to the CP environment while your 
program executes, the program continues executing while you communicate 
with CP. The default setting for the RUN operand of the SET command is 
off; usually, when you press the Attention key (twice) during program 
execution, your program is interrupted. 

SPECIAL CHABJCTEl SETS: If you are using a programming language or 
entering data that requires you to use characters that are not on your 
keyboard, you can select some characters that you do not use very often 
and establish a translate table with the SET command. For example, if 
your terminal does not have the special characters [ and ] (which have 
the hexadecimal values AD and BD, respectively) , you could issue the 
commands 

set input X ad 
set input $ bd 

Then, when you are entering data lines at your terminal, whenever you 
enter the characters "X" or M $ M f they are translated and written into 
your file as "[ " and " ]". When you display these lines, the character 
positions occupied by the special characters appear to be blanks, 
because they are not available on your keyboard. If you want these 
special characters to appear on your terminal in symbolic form, you 
should issue the commands 

set output ad % 
set output bd $ 

so that when you are displaying lines that contain these characters, 
they will appear translated as % and $ on your terminal. If you are 
going to use the input and output functions together, you must set the 
output character first; if you set the input character first, then you 
are unable to set the output function. 

If you are an APL user and have the special APL type font or the APL 
3270 feature and keyboard, you can tell VM/370 to use APL translation 
tables with the command 

cp terminal apl on 



Commands To Create, Modify, and Move Data Files and Programs 

The CMS command language provides you with many different ways of 
manipulating files. A file, in CMS, is any collection of data; it is 
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most often a disk file, but it may also be contained on cards or tape, 
or it may be a printed or punched output file. 



COMMANDS THAT CREATE FILES 

You create files in CMS by several methods; either specifically or by 
default. The EDIT command invokes the CMS Editor to allow you to create 
a file directly at your terminal. You must specify a file identifier 
when you are creating a new file: 

edit mother goose 

In this example, the file has an identifier, or fileid, of MOTHER 
GOOSE. The EDIT subcommand INPUT allows you to begin inserting lines of 
data or source code into this file. When you issue the subcommands FILE 
or SAVE, the lines that you have entered are written into a CMS disk 
file. 

Files are created, and sometimes named, by default, with the 
following types of commands: 

• Commands that invoke programming language processors or compilers. 
For example, if you issue the command 

assemble myfile 

the assembler assembles source statements from an existing CMS file 
named MYFILE ASSEMBLE and produces an output file containing object 
code, as well as a listing. The files that are created are named: 

MYFILE TEXT 
MYFILE LISTING 

• Commands that load CMS files onto a disk from cards or tapes. These 
commands are READCARD, TAPE LOAD, and DISK LOAD. 

• The LISTFILE and LISTIO commands with the EXEC option create files 
named CMS EXEC and $LISTIO EXEC which you can execute as EXEC 
procedures. 

• The TAPPDS and TAPEMAC commands create CMS disk files from OS data 
sets on tape. If the data set is a partitioned data set, the TAPPDS 
command creates individual CMS files from each of the members; the 
TAPEMAC command creates a CMS macro library, called a MACLIB, from an 
OS macro library. 

• The MOVEFILE and FILEDEF commands, used together, can copy OS or DOS 
data sets or files into CMS files; they can also copy files from 
cards or tapes. 

• CMS/DOS commands SSERV, ESERV, RSERV, and PSERV copy DOS files from 
source statement, relocatable, and procedure libraries into CMS 
files. 

• Some CMS commands produce maps, or lists of files, data sets, or 
program entry points. For example, if you issue the command 

tape scan (disk 

A CMS disk file named TAPE MAP is created that contains a list of the 
CMS files that exist on a tape attached to your virtual machine at 
virtual address 181. 

Section 3. What You Can Do With VM/370-CMS Commands 41 



Some commands create new files from files that already exist on your 
virtual disks. The creation may involve a simple copy operation, or it 
may be a combining of many files of one type into a larger file of the 
same or a different type: 

« The COPYFILE command, in its simplest form, copies a file from one 
virtual disk to another: 

copyfile yourprog assemble b myprog assemble a 

• The MACLIB and TXTLIB commands create libraries from MACRO or COPY 
files, or from TEXT (object) files. 

» The SORT command rearranges (in alphameric sequence) the records in a 
file and creates a new file to contain the result. You have to 
specify the name of the new file: 

sort nonseq recs a seq recs a 

«• The GENMOD command creates, from object modules that you have loaded 
into your virtual storage area, nonrelocatable modules. For example, 
the commands 

load test 
genmod payroll 

create a file named PAYROLL MODULE, which you can then execute as a 
user-written CMS command. 

• The DOSLKED command creates or adds members to DOSLIBs, which are 
libraries containing link-edited CMS/DOS program phases. 

• The UPDATE command creates an updated source file and special update 
files when you use it to apply updates to your source programs. 



COMMANDS THAT MODIFY DISK FILES 

You can use the CMS Editor to modify existing files on your virtual 
disks. You issue the EDIT command, giving the file identifier: 

edit old file 

CMS Editor subcommands allow you to make minor specific changes or 
global changes, which can affect many lines in a file at one time. 

The MACLIB and TXTLIB commands also allow you to modify CMS macro and 
text libraries. You can add, delete, or replace members in these 
libraries using these commands. 

The COPYFILE command has some options that allow you to change a file 
without creating a new output file. For example, if you enter the 
command 

copyfile my file a (lowcase 

then all of the uppercase characters in the file MY FILE are translated 
to lowercase. 

You can change the file identifier of a file using the RENAME 
command: 
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rename test file a1 good file a1 

The ERASE command deletes files from your virtual disks: 

erase temporary file b1 

For additional examples of CMS file system commands, see "Appendix D: 
Sample Terminal Sessions." 

COMMANDS TO MOVE FILES 

You can use CMS commands to transfer a data file from one device or 
medium to another device of the same or of a different type. The types 
of movement, and the commands to use, are described briefly here and in 
detail in "Section 7. Using Real Printers, Punches, Readers, and 
Tapes." 

If you need to transfer files between virtual machines, you can use 
the PUNCH or DISK DUMP commands to punch virtual card image records. 
These are then placed in the virtual card reader of the receiving 
virtual machine. 

Before you use either of these commands, you must indicate the output 
disposition of the files. You do this with the CP SPOOL command: 

cp spool OOd to mickey 

Then, you can use the PUNCH command to punch virtual card images: 

punch acct records 

The file ACCNT RECORDS is spooled to the userid MICKEY'S virtual card 
reader. If the CMS file you are transferring does not have fixed- 
length, 80-character (card image) records, you can use the command 

disk dump acct records 

The CMS TAPE command allows you to dump CMS files onto tape, or to 
restore previously dumped files: 

tape dump archive file 
tape load archive file 

VM/ 370 also provides a special utility program, DASD Dump Restore, 
that allows you to dump the entire contents of your virtual disk onto a 
tape and then later restore it to a disk. You might use this program, 
invoked by the DDR command in CMS, to back up your data files before 
using them to test a new program. 



COMMANDS TO PRINT FILES AND PUNCH CARDS 

The commands that you use most often to print and punch CMS files are 
the commands PRINT and PUNCH. For example, 

print myprog listing 

prints the contents of the LISTING file on the system printer, and 

punch myprog assemble 
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punches the assembler language source statement file onto cards. You 
can also punch members of MACLIBs and TXTLIBs: 

punch cmslib maclib (member fscb 

Some CMS commands have a PRINT option, so that instead of having some 
kinds of output displayed at your terminal or placed in a disk file, you 
can request to have it printed on the real system printer. For example, 
if you want a list of the contents of a macro library to print, you 
could issue the command 

maclib map mylib (print 

You can see the contents of a file displayed at your terminal by 
using the TYPE command: 

type week3 report 

you can specify, on the TYPE command, that you want to see only some 
specific records in this file: 

type week3 report a 1 20 



Commands To Develop and Test OS and CMS Programs 

Use CMS to prepare programs: you can create them with the CMS Editor, or 
write them onto your CMS disks using any of the methods discussed 
above. You can also assemble or compile source programs directly from 
cards, tapes, or OS data sets. If your source program is in a CMS disk 
file, then during the development process you can use the editor to make 
corrections and updates. 

To compile your programs, use the assembler or any of the language 
processors available at your installation. If your program uses macros 
that are contained in either system or private program libraries, you 
must make these libraries known to CMS by using the GLOBAL command: 

global maclib cmslib asmlib 

In this example, you are using two libraries: the CMS macro library, 
CMSLIB MACLIB, and a private library, named ASMLIB MACLIB. 

The output from the compilers, in relocatable object form, is stored 
on a CMS disk as a file with the filetype of TEXT. To load TEXT files 
into virtual storage to execute them, use the LOAD command: 

load myprog 

The LOAD command performs the linkage editor function in CMS. If 
MYPROG contains references to external routines, and these routines are 
the names of CMS TEXT files, those TEXT files are automatically included 
in the load. If you receive a message telling you that there is an 
undefined name (which might happen if you have a CSECT name or entry 
point that is not the same as the name of the TEXT file that contains 
it) , you can then use the INCLUDE command to load this TEXT file: 

include scanrtn 

When you have loaded the object modules into storage, you can begin 
program execution with the START command: 

start 
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If you want to begin execution at a specified entry point, enter 

start scanl 

where SCAN 1 is the name of a control section, entry point, or 
procedure. 

If you are testing a program that either reads or writes files or 
data sets using OS macros, you must use the FILEDEF command to supply a 
file definition to correspond to the ddname you specify in your program. 
The command 

filedef indd reader 

indicates that the input file is to be read from your virtual card 
reader. A disk file might be defined: 

filedef outdd disk out file a1 

The FILEDEF command, in CMS, performs the same function as a data 
definition (DD) card in OS. 

The commands to load and execute OS programs are discussed in 
"Section 8. Developing OS Programs Under CMS." 

The RUN command, which is actually an EXEC procedure, combines many 
of these commands for you, so that if you want to compile, load, and 
execute a single source file, or load and execute a TEXT or MODULE file, 
you can use the RUN command instead of issuing a series of commands. See 
the discussion of the RUN command in VMZ17 0: CMS Command and Macro 
Reference for a list of the OS language processors available. 



Commands To Develop and Test DOS Programs 

CMS simulates many functions of the Disk Operating System (DOS/VS) in 
the CMS/DOS environment. CMS/DOS is not a separate system, but is part 
of CMS. When you enter the command 

set dos on 

you are in the CMS/DOS environment. If you want to use the libraries on 
the DOS/VS system residence volume, you should access the disk on which 
it resides and specify the mode letter on the SET DOS ON command line: 

access 132 c 
set dos on c 

Using commands that are available only in the CMS/DOS environment, 
you can assign system and programmer logical units with the ASSGN 
command: 

assgn sys200 reader 

If the device is a disk device, you can set up a data definition with 
the DLBL command: 

assgn syslOO b 

dlbl infile b dsn myinput file (syslOO 

You can find out the current logical unit assignments and active file 
definitions with the LISTIO and QUERY DLBL commands, respectively: 
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listio a 
query dlbl 

If you are an assembler language programmer, you can assemble a 
source file with the ASSEMBLE command: 

assemble myprog 

A CMS file with a filetype of DOSLIB simulates a DOS core image 

library; you can link-edit TEXT files or relocatable modules from a DOS 

relocatable library and place the link-edited phase in a DOSLIB using 
the DOSLKED command: 

doslked myprog newlib 

Then, use the GLOBAL command to identify the phase library and issue the 
FETCH command to bring the phase into virtual storage: 

global doslib newlib 
fetch myprog 

The START command begins program execution: 

start 

During program development with CMS, you can use DOS/VS system or 
private libraries. You can use files on these libraries or you can copy 
them into CMS files. The DSERV command displays the directories of 
DOS/VS libraries. The command 

dserv cd 

produces a copy of the directory for the core image library. To copy 
phases from relocatable libraries into CMS TEXT files, you could use the 
RSERV command : 

rserv oldprog 

The SSERV and ESERV commands are available for you to copy files from 
source statement libraries, or copy and de-edit macros from E 
sublibraries. Also, the PSERV command copies procedures from the 
procedure library. 

The CMS/DOS commands are described in more detail in "Section 9. 
Developing DOS Programs Under CMS." 



Commands Used in Debugging Programs 

When you execute your programs under CMS, you can debug them as they 
execute, by forcing execution to halt at specific instruction addresses. 
You do this by entering the debug environment before you issue the START 
command. You enter the debug environment with the DEBUG command: 

debug 

To specify that execution be stopped at a particular virtual address, 
you can use the BREAK subcommand to set a breakpoint. For example, 

break 1 20ad0 
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Then, when this instruction is encountered during the execution of the 
program, the debug environment is entered and you can examine registers 
or specific storage locations, or print a dump of your virtual storage. 
Subcommands that do these things might look like the following: 

gpr 15 
x 20c12 8 

dump 20000 * 

If, instead of using the CHS DEBUG subcommands, you use the CP ADSTOP 
command to set address stops, for example, 

cp adstop 20ad0 

then, in the CP environment, you can use CP commands to do the same 
things, for example 

cp display g 

cp display 20c12.8 

cp dump 20000 

Both sets of commands shown in these examples result in displays of (1) 
the contents of your virtual machine's general purpose registers, (2) a 
display of eight bytes of storage beginning at location X*20C12* and (3) 
a dump of virtual storage from location X 1 20000* to the end. 

You can also use the CMS SVCTRACE command and the CP TRACE commands 
to see a record of interrupt activity in your virtual machine. 

The DEBUG subcommands and the CNS and CP debugging facilities are 
described in more detail in "Section 11. How VH/370 Can Help You Debug 
Your Programs.* 1 



Commands To Request Information 

All of the CP and CHS commands discussed in this section have reguired 
some action on your part: you set your terminal characteristics, 
manipulate disk files, develop, compile, and test programs, and control 
your virtual machine devices and spool files. During a terminal session 
you can change the status of many of your devices and virtual machine 
characteristics, modify the files on your disks and create spool files. 
VM/370 provides many commands to help you find out what is and what is 
not currently defined in your virtual machine. 



COHHANDS TO REQUEST INFORHATIOH ABOUT TERHINAL CHARACTERISTICS 

You can find out the status of your terminal characteristics by using 
the CP command QUERY with the TERHINAL or SET operands. If you issue the 
command 

cp guery terminal 

you can see the settings for all of the functions controlled by the CP 
TERHINAL command, including the current line size and line editing 
symbols. 

Similarly, the command 

cp guery set 
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tells you the settings for the functions controlled by the CP SET 
command, such as error message display, and the MSG and WNG flags. 

For most of the functions controlled by the CMS SET command, there 
are corresponding CMS QUERY command operands; to find out a particular 
setting, you must specify the function in the QUERY command. For 
example, 

guery input 

lists the current settings in effect for input character translation. 
Other functions that you can guery this way are: 

BLIP INPUT REDTYPE 

IMPCP OUTPUT SYNONYM 

IMP EX RDYMSG 



COMMANDS TO REQUEST INFORMATION ABOUT DATA FILES 

Use the LISTFILE command to get information about CMS files. The 
information you can obtain from the LISTFILE command includes: 

• The names of all the files on your A-disk: 

listf ile 

• The names of all the files on any other accessed disk: 

listfile * * b 

• The names of all files that have the same filename: 

listfile myprog * 

• The names of all files with the same filetype: 

listfile * assemble 

• The record length and format, blocksize, creation date and disk label 
for a particular file: 

listfile records saved a2 (label 

Use the STATE command to find out whether a certain file exists: 

state sales list c 

If you want to know if the file is on a read/write disk, you can use the 
STATEH command. 

To find out what CMS libraries have been made available, you can use 
the commands: 

guery doslib 
guery maclib 
guery txtlib 
guery library 

To find out what members are contained in a particular macro or text 
library use the commands: 
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maclib map mylib (term 
txtlib map proglib (term 

The MODMAP command displays a load map of a MODULE file: 

modmap payroll 

To examine load maps created by the LOAD command, use the TYPE 
command: 

type load map a5 

The TYPE command can also be used to display the contents of any CMS 
file. To examine large files, you can use the PRINT command to spool a 
copy to the high-speed printer. 

To compare the contents of two files to see if they are identical, 
use the COMPARE command: 

compare labor stat a1 labor stat b1 

Any records in these files that do not match are displayed at your 
terminal. 

If you have OS or DOS disks attached to your virtual machine, you can 
display a list of OS data sets or DOS files by using the LISTDS command, 
for example 

listds d 

displays a list of the data sets or files on the OS or DOS disk accessed 
as your D-disk. 



COMMANDS TO REQUEST INFORMATION ABOUT YOUR VIRTUAL DISKS 

Use the CP QUERY command to find out: 

• What virtual disks are currently part of your configuration: 

cp guery virtual dasd 

• Whether a particular virtual disk address is in use: 

cp guery virtual 291 

• What users might be linked to one of your disks: 

cp guery links 330 

The CMS QUERY command can tell you about your accessed disks. If you 
enter 

guery disk a 

you can find out the number of files on your A-disk, the amount of space 
that is being used, and its percentage of the total disk space, and the 
read/write status. To get this information for all of your accessed 
disks, issue the command: 

guery disk * 
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To obtain information about the extents occupied by files on OS and DOS 
disks, enter the command 

listds * (extent 

If you want to know the current order in which your disks are 
searched for data files or programs, issue the command 

query search 

You could also use this command to find out what disks you have 
accessed, what filemode letters you have assigned to them, whether they 
are read/write or read-only, and whether they are CMS, OS, or DOS 
disks. 

COMMANDS TO REQUEST INFORMATION ABOUT YOUR VIRTUAL MACHINE 

If you issue the command 

cp query virtual 

you can find out the status of your virtual machine configuration. You 
can also request specific information; for example, the command 

cp query storage 

gives you the amount of virtual storage you have available. 

To find out the current spooling characteristics of your printer, 
punch, or reader, issue the commands 

cp query OOe 
cp query OOd 
cp query 00c 

To see information about all three at once, use 

cp query ur 

For the status of spool files on any of these devices, issue the 
commands 

cp query printer 
cp query punch 
cp query reader 

Using these commands, you can request the status of particular spool 
files by referring to the spoolid number, for example: 

cp query printer 4187 

You can also request additional information about the files, including 
file identification and creation time: 

cp query reader all 

If you want to know the total number of spool files associated with 
your virtual machine, you can use the command 

cp query files 

The response to this message is the same as the message you receive if 
you have spool files when you log on. 
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The file is the essential unit of data in the CMS system. CMS disk 
files are unique to the CMS system and cannot be read or written using 
other operating systems. When you create a file in CMS, you name it 
using a file identifier. The file identifier consists of three fields: 

• Filename (fn) 

• Filetype (ft) 

• Filemode (fm) 

When you use CMS commands and programs to modify, update, or 
reference files, you must identify the file by using these fields. Some 
CMS commands require you to enter only the filename, or the filename and 
filetype; others require you to enter the filemode field as well. This 
section contains information about the things you must consider when you 
give your CMS files their identifiers, notes on the file system commands 
that create and modify CMS files, and additional notes on using CMS 
disks. 



CMS File Formats 

The CMS file management routines write CMS files on disk in 800-byte 
physical blocks, regardless of whether they have fixed- or 
variable-length records. For most of your CMS applications, you never 
need to specify either a logical record length and record format or 
block size when you create a CHS file. 

When you create a file with the CMS Editor, the file has certain 
default characteristics, based on its filetype. The special filetypes 
recognized by the editor, and their applications, are discussed under 
"What are Reserved Filetypes?" 

VSAM files written by CMS are in the same format as VSAM files 
written by OS/VS or DOS/VS and are recognized by those operating 
systems. You cannot, however, use any CMS file system commands to read 
and write VSAM files, because VSAM file formats are unique to the 
Virtual Storage Access Method. 

A single CMS file can contain up to 12,848,000 bytes of data grouped 
into up to 65,535 logical records, all of which must be on the same 
minidisk. If the file is a source program, the file size limit may be 
smaller. The maximum number of files per real disk is 3400 for a 3330, 
3333, 3340, or 3350 disk, or 3500 for a 2314 or 2319. 



How CMS Files Get Their Names 

When you create a CMS file, you can give it any filename and filetype 
you wish. The rules for forming filenames and filetypes are: 

• The filename and filetype can each be from 1- to 8 characters. 

• The valid characters are A-Z, 0-9, and $, #, a 

When you enter a command line into the VM/370 system, your input line 
is always translated, by VM/370, into uppercase characters. So, when you 
specify a file identifier, you can enter it in lowercase. 
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Remember that, by default, the # and S characters are line editing 
symbols in VM/370; when you use them to identify a file, you must 
precede them with the logical escape symbol (") . 

The third field in the file identifier, the filemode, indicates the 
mode letter (A-G, S, Y, or Z) currently assigned to the virtual disk on 
which you want the file to reside. When you use the CMS Editor to 
create a file, and you do not specify this field, the file you create is 
written on your A-disk, and has a filemode letter of A. 

The filemode letter, for any file, can change during a terminal 
session. For example, when you log on, your virtual disk at address 191 
is accessed as your A-disk, so a file on that disk named SPECIAL EVENTS 
has a file identifier of: 

SPECIAL EVENTS A 

If, however, you later access another disk as your A-disk, and access 
your 191 as your B-disk, then this file has a file identifier of: 

SPECIAL EVENTS B 



DUPLICATING FILENAMES AND FILETYPES 

You can give the same filename to as many files on a given disk as you 
want, as long as you assign them different filetypes. Or you can create 
many files with the same filetype but different filenames. 

For the most part, filenames that you choose for your files have no 
special significance to CMS. If, however, you choose a name that is the 
same as the name of a CMS command, and the file that you assign this 
name to is an executable module or EXEC procedure, then you may 
encounter difficulty if you try to execute the CMS command whose name 
you duplicated. 

For an explanation of how CMS identifies a command name, see "CMS 
Command Search Order" later in this section. 

Many CMS commands allow you to specify one or more of the fields in a 
file identifier as an asterisk (*) or equal sign (=) , which identify 
files with similar fileids. 



i?sina Asterisks (*) in Fileids 

Some CMS commands that manipulate disk files allow you to enter the 
filename and/or filetype fields as an asterisk (*) , indicating that all 
files of the specified f ilename/f iletype are to be modified. These 
commands are: 

COPYFILE RENAME 
ERASE TAPE DUMP 

For example, if you specify 

erase * test a 

all files with a filetype of TEST on your A-disk are erased. 
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Similarly, if you enter the command 

rename temp * b perm = = 

all files with a filename of TEMP are renamed to have filenames of PERM; 
the existing filetypes of the files remain unchanged. 

The LISTFILE command allows you to request similar lists. If you 
specify an asterisk for a filename or filetype, all of the files of that 
filename or filetype are listed. There is an additional feature that you 
can use with the LISTFILE command, to obtain a list of all the files 
that have a filename or filetype that begin with the same character 
string. For example, 

listfile t* assemble 

produces a list of all files on your A-disk whose filenames begin with 
the letter T. The command 

listfile tr* a* 

produces a list of all files on your A-disk whose filenames begin with 
the letters TR and whose filetypes begin with the letter A. 



ISSlii Signs in Output Fileids 

The COPYFILE, RENAME, and SORT commands allow you to enter output file 
identifiers as equal signs (=) , to indicate that it is the same as the 
corresponding input file identifier. For example, 

copyfile myprog assemble b = = a 

copies the file MYPROG ASSEMBLE from your B-disk to your A-disk, and 
uses the same filename and filetype as specified in the input fileid for 
those positions in the output fileid. 



What Are Reserved Filetypes? 

For the purposes of most CMS commands, the filetype field is used merely 
as an identifier. Some filetypes, though, have special uses in CMS; 
these are known as "reserved filetypes." 

Nothing prevents you from assigning any of the reserved filetypes to 
files that are not being used for the specific CMS function normally 
associated with that filetype. 

Reserved filetypes also have special significance to the CMS Editor. 
When you use the EDIT command to create a file with a reserved filetype, 
the editor assumes various default characteristics for the file, such as 
record length and format, tab settings, translation to uppercase, 
truncation column, and so on. 
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FILETYPES FOE CMS COMMANDS 



Reserved filetypes sometimes indicate how the file is used in the CMS 
system: the filetype ASSEMBLE, for example, indicates that the file is 
to be used as input to the assembler; the filetype TEXT indicates that 
the file is in relocatable object form, and so on. Many CMS commands 
assume input files of particular filetypes, and require you to enter 
only the filename on the command line. For example, if you enter 

synonym test 

CMS searches for a file with a filetype of SYNONYM and a filename of 
TEST. A file named TEST that has any other filetype is ignored. 

Some CMS commands create files of particular filetypes, using the 
filename you enter on the command line. The language processors do this 
as well; if you are recompiling a source file, but wish to save previous 
output files, you should rename them before executing the command. 

Figure 2 lists the filetypes used by CMS commands and describes how 
they are used. Figure 3 lists the filetypes used by CMS/DOS commands. 

In addition to these CMS filetypes, there are special filetypes 
reserved for use by the language processors, which are IBM program 
products. These filetypes, and the commands that use them, are: 



Filetypes 
COBOL, TESTCOB 
FORTRAN, FREEFORT, 

FTnnOOl, TESTFORT 
PLI, PLIOPT 
VSBASIC, VSBDATA 



Commands 

COBOL, FCOBOL, TESTCOB 

FORTRAN, FORTGI, FORTHX 

GOFORT, TESTFORT 
DOSPLI, PLIC, PLICR, PLIOPT 
VSBASIC 



For details on how to use these filetypes, consult the appropriate 
program product documentation. 
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Filetype 
AMSERV 

ASM3705 

ASSEMBLE 

AUXxxxx 

CNTRL 

COPY 

DIRECT 

EXEC 

LISTING 

LKEDIT 
LOADLIB 



MACLIB 



MACRO 



MAP 



Command 



AMSERV 



ASM3705 
GEN3705 

ASSEMBLE 



UPDATE 



UPDATE 



MACLIB 



DIRECT 



EXEC 

GEN3705 

LISTFILE 

AMSERV 

ASSEMBLE 

ASM3705 

LKED 



LKED 



GLOBAL 
MACLIB 



MACLIB 



INCLUDE 

LOAD 

MACLIB 

TAPE 

TXTLIB 



Comments 



Contains VSAM Access Method Services control 
statements to be executed with the AMSERV 
command. 

Used by system programmers to generate the 
3704/3705 control program. 

Contains source statements for assembler 
language programs. 

Points to files that contain UPDATE control 
statements for multiple updates. 

Lists files that either contain UPDATE control 
statements or point to additional files. 

Can contain COPY control statements and macros 
or copy files to be added to MACLIBs. 

Contains entries for the VM/370 user directory 
file. The system operator controls this file. 

Can contain sequences of CMS or user-writteD 
commands, with execution control statements. 



Listings are produced by the assembler and 
the language processors as well as the AMSERV 
command. 

Contains the listing created during the 
generation of the 3704/3705 control program. 

Is a library of 3704/3705 control program 
load modules created during 3704/3705 control 
program generation. 

Library members contain macro definitions or 
copy files; the MACLIB command creates the 
library, and lists, adds, deletes, or replaces 
members. The GLOBAL command identifies which 
macro libraries should be searched during an 
assembly or compilation. 

Contains macro definitions to be added to a 
CMS macro library (MACLIB) . 

Maps created by the LOAD and INCLUDE commands 
indicate entry point locations; the MACLIB, 
TXTLIB, and TAPE commands produce MAP files. 



Figure 2. Filetypes Used by CMS Commands (Part 1 of 2) 
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Filetype 
MODULE 



SYNONYM 



SCRIPT i 



TEXT 



TX TL IB 



UPDATE 



UPDLOG 



UPDTxxxx 



ZAP 



Command 

GENMOD 

LOADMOD 

MODMAP 



SYNONYM 



SCRIPT 



ASSEMBLE 
INCLUDE 
LOAD 
TXTLIB 



GLOBAL 
TXTLIB 



UPDATE 



UPDATE 



UPDATE 



ZAP 



Comments 

MODULE files created by the GENMOD command are 
nonrelocatable executable programs. 
The LOADMOD commands loads a MODULE file for 
execution; the MODMAP command displays a map 
of entry point locations. 

Contains a table of synonyms for CMS commands 
and user-written EXEC and MODULE files. 

SCRIPT text processor input includes data and 
SCRIPT control words. 

TEXT files contain relocatable object code 
created by the assembler and compilers. The 
LOAD and INCLUDE commands load them into 
storage for execution. The TXTLIB command 
manipulates libraries of TEXT files. 

Library members contain relocatable object 
code. The TXTLIB command creates the library, 
and lists or deletes existing members. The 
GLOBAL command identifies TXTLIBs to search. 

Contains UPDATE control statements for single 
updates applied to source programs. 

Contains a record of additions, deletions, or 
changes made with the UPDATE command. 

Contains UPDATE control statements for 
multilevel updates. 

Contains control records for the ZAP command, 
which is used by system support personnel. 



^SCRIPT is an IBM Installed User Program (IUP) . 
Figure 2. Filetypes Used by CMS Commands (Part 2 of 2) 



OUTPUT FILES: TEXT AND LISTING 



Output files from the assembler and the language processors are 
logically related to the source programs by their filenames. Some of 
these files are permanent and some are temporary. For example, if you 
issue the command 

assemble myfile 

CMS locates a file named MYFILE with a filetype of ASSEMBLE and the 
system assembler assembles it. If the file is on your A-disk, then when 
the assembler completes execution, the permanent files you have are: 

MYFILE ASSEMBLE A1 
MYFILE TEXT A1 
MYFILE LISTING A1 

where the TEXT file contains the object code resulting from the 
assembly, and the LISTING file contains the program listing generated by 
the assembly. If any TEXT or LISTING file with the same name previously 
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Filetype 
COPY 



DOSLIB 



DOSLNK 



ESERV 



| Command | Comments 



EXEC 



LISTING 



MACRO 



NAP 



PROC 



TEXT 



MACLIB 
SSERV 



DOSLIB 
DOSLNK 
FETCH 
GLOBAL 

DOSLKED 



ESERV 



LISTIO 



ASSEMBLE 
ESERV 



ESERV 
MACLIB 

DOSLIB 

DOSLKED 

DSERV 



PSERV 



ASSEMBLE 

DOSLKED 

RSERV 



When the SSERV command copies books or macros 
from DOS source statement libraries, the output 
is written to CMS COPY files, which can be added 
to CMS macro libraries with the MACLIB command. 

DOS core image phases are placed in a DOSLIB by 
linkage editor, invoked with the DOSLNK command. 
The GLOBAL command identifies DOSLIBs to be 
searched when the FETCH command is executed. 

Contains linkage editor control statements for 
input to the CMS/DOS linkage editor. 

Contains input control statements for the ESERV 
utility program. 

The LISTIO command with the EXEC option creates 
the $LISTIO EXEC that lists system and 
programmer logical unit assignments. 

Listings contain processor output from the ESERV 
command, and compiler output from the assembler 
and language processors. 

Contains SYSPCH output from the ESERV program, 
suitable for addition to a CMS MACLIB file. 

The DSERV command creates listings of the 
directories of DOS libraries. The DOSLIB command 
with the MAP option produces a list of DOSLIB 
members. The linkage editor map from the DOSLKED 
command is written into a MAP file. 

The PSERV command copies procedures from DOS 
procedure libraries into CMS PROC files. 

Object decks created by the assembler or 
compilers are written into TEXT files. The RSERV 
command creates TEXT files from modules in DOS 
relocatable libraries. TEXT files can also be 
used as input to the linkage editor. 

i 



Figure 3. Filetypes Used in CMS/DOS 



existed, it is erased. The source input file, MYFILE ASSEMBLE 
neither erased nor changed. 



A1, is 



The characteristics of the TEXT and LISTING files produced by the 
assembler are the same as those created by other processors and programs 
in CMS. 

Because these files are CMS files, you can use the CMS Editor to 
examine or modify their contents. If you want a printed copy of a 
LISTING file, you can use the PRINT command to print it. If you want to 
examine a TEXT file, you can use the TYPE or PRINT command specifying 
the HEX option. 
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FILETYPES FOR TEMPORARY FILES 



The filetypes of files created by the assembler and language processors 
for use as temporary workfiles are: 



SYSUT1 
SYSUT2 
SYSUT3 
SYSUT4 



SYS001 
SYS002 
SYS003 



SYS004 
SYS005 
SYS006 



The CMS AMSERV command, executing VSAM utility functions, 
workfiles, that have filetypes of LDTFDI1 and LDTFDI2. 



uses two 



Disk space is allocated for temporary files on an as- needed basis. 
They are erased when processing is complete. If a program you are 
executing is terminated before completion, these workfiles may remain on 
your disk. You can erase them. 



CMSUT1 Files 



The CMSUT1 filetype is used by CMS commands that create files on your 
CMS disks. The CMSUT1 file is used as a workfile and is erased when the 
file is created. When a command fails to complete execution properly, 
the CMS0T1 file may not be erased. The commands, and the filenames they 
assign to files they create, are listed below. 

Command Filename 

COPYFILE COPYFILE 

DISK LOAD DISK 

EDIT EDIT 

INCLUDE DMSLDR 

LOAD DMSLDR 

MACLIB DMSLBM 

READCARD READCARD 

TAPE LOAD TAPE 

UPDATE fn (the filename of the UPDATE file) 



FILETYPES FOR DOCUMENTATION 



There are two CMS reserved filetypes that accept uppercase and lowercase 
input data. These are MEMO and SCRIPT. You can use MEMO files to 
document program notes or to write reports. The SCRIPT filetype is used 
by the SCRIPT command, which invokes a text processor that is an IBM 
Installed User Program (IUP) . 



Filemode Letters and Numbers 



The filemode field of a CMS file identifier has two characters: the 
filemode letter and the filemode number. The filemode letter is 
established by the ACCESS command, and specifies the virtual disk on 
which a file resides: A through G, S, Y, or Z. The filemode number is a 
number from to 5, which you can assign to the file when you create it 
or rename it; if you do not specify it, the value defaults to 1. How 
you access your disks and what filemode letters you give them with the 
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ACCESS command depends on how you want to use the files that are on 
them. 

For most of the reading and writing you do of files, you use your 
A-disk, which is also known as your primary disk. This is a read/write 
disk. You may access other disks in your configuration, or access 
linked-to disks, in read-only or read/write status, depending on whether 
you have a read-only or read/write link. 

When you load CMS (with the IPL command), your virtual disk at 
address 191 is accessed for you as your A-disk. Your virtual disk at 
address 190 (the system disk) is accessed as your S-disk; and the disk 
at 19E is accessed as an extension of your S-disk, with a mode letter of 
Y. In addition, if you have a disk defined at address 192, it is 
accessed for you as your D-disk. 

The actual letters you assign to any other disks (and you may 
reassign the letters A, D, and Y) , is arbitrary; but it does determine 
the CMS search order, which is the order in which CMS searches your 
disks when it is looking for a file. The order of search (when all disks 
are being searched) is alphabetical: A through G, S, Y, and Z. If you 
have duplicate file identifiers on different disks, you should check 
your disk search order before issuing commands against that filename to 
be sure that you will get the file you want. You can find out the 
current search order for your virtual disks by issuing the command: 

query search 

You can also access disks as logical extensions of other disks, for 
example: 

access 235 b/a 

The "/A" indicates that the B-disk is to be a read-only extension of the 
A-disk, and the A-disk is considered the "parent" of the B-disk. A disk 
■ay have many extensions, but only one level of extension is allowed. 



S2U Extensions Are Used 

If you have a disk accessed as an extension of another disk, the 
extension disk is automatically read-only, and you cannot write on it. 
You might access a disk as its own extension, therefore, to protect the 
files on it, so that you do not accidentally write on it, for example, 

access 235 b/b 

Another use of extensions is to extend the CMS search order. If you 
issue a command requesting to read a file, for example: 

type alpha plan 

CMS searches your A-disk for the file named ALPHA PLAN and if it does 
not find it, searches any extensions that your A-disk may have. If you 
have a file named ALPHA PLAN on your B-disk but have not accessed it as 
an extension of your A-disk, CMS will not find the file, and you will 
have to re-enter the command: 

type alpha plan b 

Additionally, if you issue a CMS command that reads and writes a 
file, and the file to be read is on an extension of a read/write disk, 
the output file is written to the parent read/write disk. The EDIT 
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command is a good example of this type of command. If you have a file 
netmed FINAL LIST on a B-disk extension of a read/write A-disk, and if 
you invoke the editor to modify the file with the command: 

edit final list 

after you have made modifications to the file, the changed file is 
written onto your A-disk. The file on the B-disk remains unchanged. 



Accessinc[ and Releasing Read-only Extensions 

When you access a disk as a read-only extension, it remains an extension 
of the parent disk as long as both disks are still accessed. If either 
disk is released, the relationship is terminated. 

If the parent disk is released, the extension remains accessed and 
you may still read files on it. If you access another disk at the mode 
letter of the original parent disk, the parent/extension relationship 
remains in effect. 

If you release a read-only extension and access another disk with the 
same mode letter, it is not an extension of the original parent disk 
unless you access it as such. For example, if you enter 

access 198 c/a 
release c 
access 199 c 

the C-disk at virtual address 199 is not an extension of your A-disk. 



WHEN TO SPECIFY FILEMODE LETTERS: READING FILES 

When you request CMS to access a file, you have to identify it so that 
CMS can locate it for you. The commands that expect files of particular 
filetypes (reserved filetypes) allow you to enter only the filename of 
the file when you issue the command, when you execute any of these 
commands, or execute a MODULE or EXEC file, CMS searches all of your 
accessed disks (using the standard search order) to locate the file. 
The CMS commands that perform this type of search are: 

AMSERV GLOBAL MODMAF 

ASSEMBLE LOAD RUN 

DOSLIB LOADMOD TXTLIB 

EXEC MACLIB 

Some CMS commands reguire you to enter the filename and filetype to 
identify a file. You may specify the filemode letter; if you do not 
specify the filemode, CMS searches only your A-disk and its extensions 
when it looks for the file. If you do specify a filemode letter, the 
disk you specify and its extensions are searched for the file. The 
commands you use this way are: 

EDIT PUNCH TAPE DUMP 

ERASE STATE TYPE 

FILEDEF SYNONYM UPDATE 
PRINT 

There are two CMS commands that do not search extensions of disks 
when looking for files. They are: 
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DISK DUMP 
LISTFIIE 

You must explicitly enter the filemode if you want to use these commands 
to list or dump files that are on extensions. 



Using Asterisks and Egual Signs 

For some CMS commands, if you specify the filemode of a file as an 
asterisk , it indicates that you either do not know or do not care what 
disk the file is on and you want CMS to locate it for you. For example, 
if you enter 

listfile myfile test * 

the LISTFILE command responds by listing all files on your accessed 
disks named MYFILE TEST. When you specify an asterisk for the filemode 
of the COPYFILE, ERASE, or RENAME commands, CMS locates all copies of 
the specified file. For example, 

rename temp sort * good sort = 

renames all files named TEMP SORT to GOOD SORT on all of your accessed 
read/write disks. An equal sign (=) is valid in output fileids for the 
RENAME, SORT, and COPYFILE commands. 

For some commands, when you specify an asterisk for the filemode of a 
file, CMS stops searching as soon as it finds the first copy of the 
file. For example, 

type myfile assemble * 

If there are files named MYFILE ASSEMBLE on your A-disk and C-disk, then 
only the copy on your A-disk is displayed. The commands that perform 
this type of search are: 

STATE 
SYNONYM 
TAPE DUMP 
TYPE 

For the COMPARE, COPYFILE, RENAME, and SORT commands, you must always 
specify a filemode letter, even if it is specified as an asterisk. 



WHEN TO SPECIFY FILEMODE LETTERS: WRITING FILES 

When you issue a CMS command that writes a file onto one of your virtual 
disks, and you specify the output filemode, CMS writes the file onto 
that disk. The commands that require you to specify the output filemode 
are: 

COPYFILE 

RENAME 

SORT 

The commands that allow you to specify the output filemode, but do 
not require it, are: 
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COMPARE 


PRINT 


DISK DUMP 


PUNCH 


EDIT 


RUN 


FILEDEF 


SORT 



FILEDEF TAPE LOAD 
GENMOD TAPPDS 

READCARD UPDATE 

When you do not specify the filemode on these commands, CMS writes the 
output files onto your A-disk. 

Some CMS commands that create files always write them onto your 
A-disk. The LOAD and INCLUDE commands write a file named LOAD MAP A5. 
The LISTFILE command creates a file named CMS EXEC, on your A-disk. The 
CHS/DOS commands DSERV, ESERV, SSERV, PSERV, and RSERV also write files 
onto your A-disk. 

Other commands that do not allow you to specify the filemode write 
output files either: 

• To the disk from which the input file was read 

• To your A-disk, if the file was read from a read-only disk. 

These commands are: 

AMSERV 
MACLIB 
TXTLIB 
UPDATE 

The SORT command also functions this way if you specify the output 
filemode as an asterisk (*) . 

In addition, many of the language processors, when creating work 
files and permanent files, write onto the first read/write disk in your 
search order, if they cannot write on the source files 1 s disk or its 
parent. 



HOW FILEMODE NUMBERS ARE USED 

Whenever you specify a filemode letter to reference a file, you can also 
specify a filemode number. since a filemode number for most of your 
files is 1, you do not need to specify it. The filemode numbers 0, 2, 
3,, 4, and 5 are discussed below. Filemode numbers 6 through 9 are 
reserved for IBM use. 

lAlejoilii Q : A filemode number of assigned to a file makes that file 
private. No other user may access it unless they have read/write access 
to your disk. If someone links to your disk in read-only mode and 
requests a list of all the files on your disk, the files with a filemode 
of are not listed. 

Filemode 2: Filemode 2 is essentially the same, for the purposes of 
reading and writing files, as filemode 1. Usually a filemode of 2 is 
assigned to files that are shared by users who link to a common disk, 
like the system disk. Since you can access a disk and specify which 
files on that disk you want to access, files with a filemode of 2 
provide a convenient subset of all files on a disk. For example, if you 
issue the command: 

access 489 e/a * * e2 

you can only read files with a filemode of 2 on the disk at virtual 
address 489. 
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Filemode 3: Files with a filemode of 3 are erased after they are read. 
If you create a file with a filemode of 3 and then request that it be 
printed, the file is printed, and then erased. You can use this filemode 
if you write a program or EXEC procedure that creates files that you do 
not want to maintain copies of on your virtual disks. You can create the 
file, print it, and not have to worry about erasing it later. 

The language processors and some CMS commands create work files and 
give these work files a filemode of 3. 

liliUSode 4: Files with a filemode of 4 are in OS simulated data set 
format. These files are created by OS macros in programs running in 
CMS. You specify that a file created by a program is to have OS 
simulated data set format by specifying a filemode of 4 when you issue 
the FILEDEF command for the output file. If you do not specify a 
filemode of 4 , the output file is created in CMS format. 

You can find more details about OS simulated data sets in "Section 
8. Developing OS Programs Under CMS." 

Note: There are no filemode numbers reserved for DOS or VSAM data sets, 
since CMS does not simulate these file organizations. 

Fii§12^© 5: This filemode number is the same, for purposes of reading 
and writing, as filemode 1. You can assign a filemode of 5 to files that 
you want to maintain as logical groups, so that you can manipulate them 
in groups. For example, you can reserve the filemode of 5 for all files 
that you are retaining for a certain period of time; then, when you want 
to erase them, you could issue the command: 

erase * * a5 

The CMS commands that create files with a filetype of MAP assign these 
files a filemode of 5. 



*h.©fi £2 la£§£ Iii§12^e Mulders 

You can assign filemode numbers when you use the following commands: 

COPYFILE: You can assign a filemode number when you create a new file 
with the COPYFILE command. To change only the filemode number of an 
existing file, you must use the REPLACE option. For example 

copyfile test module a1 = = a2 (replace 

changes the filemode number of the file TEST MODULE A from 1 to 2 . 

EDIT: You can assign a filemode number when you create a file with the 
CMS Editor. To change the filemode number of an existing file, use the 
RENAME or COPYFILE commands, or use the FMODE subcommand when you are in 
the edit environment. 

HkMh* I1LJIJEF: When you assign file definitions to disk files for 
programs or CMS command functions, you can specify a filemode number. 

GENMOD: You can specify a filemode number on the GENMOD command line. 
To change the filemode number of an existing MODULE file, use the RENAME 
or COPYFILE commands. 

SIMJCARD: You can assign a filemode number when you specify a file 
identifier on the READCARD command line, or on a READ control card. 
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RENAME: When you specify the fileids on the RENAME command, you can 
specify the filemode numbers for the input and/or output files. 

SORT: You can specify filemode numbers for the input and/or output 
fileids on the SORT command line. 



Managing Your CMS Disks 

The number of files you can write on a CMS disk depends on both the size 
of the disk and the size of the files that it contains. You can find 
out how much space is being used on a disk by using the QUERY DISK 
command. For example, to see how much space is on your A-disk, you would 
enter 

guery disk a 

The response may be something like this: 

A (191): 171 FILES; 1221 REC IN USE, 107 LEFT (of 1328), 
92% FULL (5 CYL) , 3330, R/W 

When a disk is becoming full, you should erase whatever files you no 
longer need. Or dump to tape files that you need to keep but do not need 
to keep active on disk. 

When you are executing a command or program that writes a file to 
disk, and the disk becomes full in the process, you receive an error 
message, and you have to try to clear some space on the disk before you 
can attempt to execute the command or program again. To avoid the 
delays that such situations cause, you should try to maintain an 
awareness of the usage of your disks. If you cannot erase any more 
files from your disks, you should contact installation support personnel 
about obtaining additional read/write CMS disk space. 



CMS File Directories 

Each CMS disk has a master file directory that contains entries for each 
of the CMS files on the disk. When you access a disk, information from 
the master file directory is brought into virtual storage and written 
into a user file directory. The user file directory has an entry for 
each file that you may access. If you have accessed a disk specifying 
only particular files, then the user file directory contains entries 
only for those files. 

If you have read/write access to a disk, then each time you write the 
file onto disk the user file directory and master file directory are 
updated to reflect the current status of the disk. If you have read-only 
access to a disk, then you cannot update the master file directory or 
user file directory. If you access a read-only disk while another user 
is writing files onto it, you may need to periodically reissue the 
ACCESS command for the disk, to obtain a fresh copy of the master file 
directory . 

Note: You should never attempt to write on a disk at the same time as 
another user. 

The user file directory remains in virtual storage until you issue 
the RELEASE command specifying the mode letter or virtual address of the 
disk. If you detach a virtual disk (with the CP DETACH command) without 
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releasing it, CMS does not know that the disk is no longer part of your 
virtual machine. When you attempt to read or write a file on the disk 
CMS assumes that the disk is still active (because the user file 
directory is still in storage) and encounters an error when it tries to 
read or write the file. 

A similar situation occurs if you detach a disk and then add a new 
disk to your virtual machine using the same virtual address as the disk 
you detached. For example, if you enter the following sequence of 
commands: 

cp link userl 191 195 rr rpass 

access 195 d 

cp detach 195 

cp link user2 193 195 rr rpass2 

listfile * * d 

the LISTFILE command produces a list of the files on OSERl's 191 disk; 
if you attempt to read one of these files, you receive an error 
message. You must issue the ACCESS command to obtain a copy of the 
master file directory for USER2's 193 disk. 

The entries in the master file directory are sorted alphamerically by 
filename and filetype, to facilitate the CMS search for particular 
files. When you are updating disk files, the entries in the user file 
directory and master file directory tend to become unsorted as files are 
created, updated, and erased. When you use the RELEASE command to 
release a read/write disk, the entries are sorted and the master file 
directory is rewritten. If you or any other user subsequently access 
the disk, the file search may be more efficient. 



CMS Command Search Order 



When you enter a command line in the CMS environment, CMS has to locate 
the command to execute. If you have EXEC or MODULE files on any of your 
accessed disks, CMS treats them as commands, also: they are known as 
user-written commands. 

As soon as the command name is found, the search stops and the 
command is executed. The search order is: 

1. EXEC file on any currently accessed disk. CMS uses the standard 
search order (A through G, S, Y, and Z.) 

2. Valid abbreviation or truncation for an EXEC file on any currently 
accessed disk, according to current SYNONYM file definitions in 
effect. 

3. A command that has already been loaded into the transient area. 
The transient area commands are: 



ACCESS 

ASSGN 

COMPARE 

DISK 

DLBL 

FILEDEF 

GENDIRT 

GLOBAL 



LISTFILE 

MODMAP 

OPTION 

PRINT 

PUNCH 

QUERY 

READCARD 



RELEASE 

RENAME 

SET 

SVCTRACE 

SYNONYM 

TAPE 

TYPE 
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4. A nucleus-resident command. The nucleus-resident CMS commands are: 

CP GENMOD START 

DEBUG INCLUDE STATE 

ERASE LOAD STATEH 

FETCH LOADMOD 

5. Command module on any currently accessed disk. (All the remaining 
CMS commands are disk resident and execute in the user area.) 

6. Valid abbreviation or truncation for nucleus-resident or transient 
area command module. 

7. Valid abbreviation or truncation for disk resident command. 

For example, if you create a command module that has the same name as 
a CMS nucleus-resident command, your command module cannot be executed, 
since CMS locates the nucleus-resident command first, and executes it. 

Figure 4 shows more details of the command search order; you can find 
a complete description of the search order in the VM^370: System 
Programmer's Guide. 
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Figure 4. How CMS Searches for the Command to Execute 
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Section 5. The CMS Editor 



In CMS usage, the term edit is used in a variety of ways, all of which 
refer, ultimately, to the functions of the CMS Editor, which is invoked 
when you issue the EDIT command. 

To edit a file means to make changes, additions, or deletions to a 
CMS file that is on a disk, and to make these changes interactively: you 
instruct the editor to make a change, the editor does it, and then you 
request another change. 

You can edit a file that does not exist; when you do so, you create 
the file online, and can modify it as you enter it. 

To file a file means to write a file you are editing back onto a 
disk, incorporating any changes you made during the editing session. 
When you issue the FILE subcommand to write a file, you are no longer in 
the environment of the CMS Editor, but are returned to the CMS 
environment. You can, however, write a file to disk and then continue 
editing it, by using the SAVE subcommand. 

An editing session is the period of time during which a file is in 
your virtual storage area, from the moment you issue the EDIT command 
and the editor responds EDIT: until you issue the FILE or QUIT 
subcommands to return to the CMS command environment. 



The EDIT Command 

When you issue the EDIT command you must specify the filename and 
filetype of the file you want to edit. If you issue 

edit test file 

CMS searches your A-disk and its extensions for a file with the 
identification TEST FILE. If the file is not found, CMS assumes that you 
want to create the file and issues the message 

NEW FILE: 
EDIT: 

to inform you that the file does not already exist. 

If the file exists on a disk other than your A-disk and its 
extensions, or if you want to create a file to write on a read/write 
disk other than your A-disk, you must specify the filemode of the file: 

edit test file b 

In this example, your B-disk and its extensions are searched for the 
file TEST FILE. 

After you issue the EDIT command, you are in edit mode, or the 
environment of the CMS Editor. If you have specified the filename and 
filetype of a file that already exists, you can now use EDIT subcommands 
to make changes or corrections to lines in that file. If you want to 
add records to the file, as you would if you are creating a new file, 
issue the EDIT subcommand 
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input 

to enter input node. Every line that you enter is considered a data line 
to be written into the disk file. For most filetypes, the editor 
translates all of your input data to uppercase characters, regardless of 
how you enter it. For example, if you create a file and enter input 
mode as follows: 

edit myfile test 

NEW FILE: 

EDIT: 

input 

INPUT: 

This is a file I am 

learning to create with the CMS Editor. 

the lines are written into the file as 

THIS IS A FILE I AM 

LEARNING TO CREATE WITH THE CMS EDITOR. 

You can use the VM/370 logical line editing symbols to modify data 
lines as you enter them. 

To return to edit mode to modify a file or to terminate the edit 
session, you must press the Return key on a null line. If you have just 
entered a data line, for example, and your terminal's typing element or 
cursor is positioned at the last character you entered, you must press 
the Return key once to enter the data line, and a second time to enter a 
null line. 

You may also use the logical line end symbol to enter a null line, 
for example, 

last line of input* 
* 

Both of these lines cause you to return to edit mode from input mode. 

If you do not enter a null line, but enter an EDIT subcommand or CMS 
command, the command line is written into your file as input. The only 
exception to this is a line that begins with the characters #CP. These 
characters indicate that the command is to be passed immediately to CP 
for processing. 



WRITING A FILE ONTO DISK 

A file you create and the modifications that you make to it during an 
edit session are not automatically written to a disk file. To save the 
results, you can do the following: 

• Periodically issue the subcommand 

save 

to write onto disk the contents of the file as it exists when you 

issue the subcommand. Periodically issuing this EDIT subcommand 

protects your data against a system failure; you can be sure that 
changes you make are not lost. 

• At the beginning of the edit session, issue the AOTOSAVE subcommand, 
with a number: 
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autosave 10 

Then, for every tenth change or addition to the file, the editor 
issues an automatic save request, which writes the file onto disk. 

• At the end of the edit session, issue the subcommand 

file 

This subcommand terminates the edit session, writes the file onto 
disk, replacing a previous file by that name (if one existed) , and 
returns you to the CMS environment. You can return to the edit 
environment by issuing the EDIT command, specifying a different file 
or the same file. 

The editor decides which disk to write the file onto according to the 
following hierarchy: 

• If you specify a filemode on the FILE or SAVE subcommand line, the 
file is written onto the specified disk. 

• If the current filemode of the file is the mode of a read/write disk, 
the file is written onto that disk. (If you have not specified a 
filemode letter, it defaults to your A-disk.) 

• If the filemode is the mode of a read-only extension of a read/write 
disk, the file is written onto the read/write parent disk. 

• If the filemode is the mode of a read-only disk that is not an 
extension of a read/write disk, the editor cannot write the file and 
issues an error message. 

See "Changing File Identifiers" for information on how you can tell 
the editor what disk to use when writing a file. 

If you are editing a file and decide, after making several changes, 
that you do not wish to save the changes, you can use the subcommand 

quit 

No changes that you made since you last used the SAVE subcommand (or the 
editor last issued an automatic save for you) are retained. If you have 
just begun an edit session, and have made no changes at all to a file, 
and for some reason you do not want to edit it at all (for example, you 
misspelled the name, or want to change a CMS setting before editing the 
file) , you can use the QUIT subcommand instead of the FILE subcommand to 
terminate the edit session and return to CMS. 

A file must have at least one line of data in order to be written. 



EDIT SUBCOMMANDS 

While you are in the edit environment, you can issue any EDIT subcommand 
or macro. An edit macro is an EXEC file that contains a sequence of EDIT 
subcommands that execute as a unit. You can create your own EDIT 
subcommands with the CMS EXEC facility. EDIT subcommands provide a 
variety of functions. You can: 

• Position the current line pointer at a particular line, or record, in 
a file. 
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«» Control which columns of a file are displayed or searched during an 
editing session. 

» Modify data lines. 

* Describe the characteristics that a file and its individual records 
will have 

<» Automatically write and update seguence numbers for fixed-length 
records. 

o Edit files by line number. 

«» Control the editing session. 

Entering EDIT Subcommands 

Like CHS commands, EDIT subcommands have a subcommand name and some have 
operands. In most cases, a subcommand name (or its truncation) can be 
separated from its operands by one or more blanks, or no blanks. For 
example, the subcommand lines 

type 5 
ty 5 
t5 

are eguivalent. 

Several subcommands also use delimiters, which enclose a character 
string that you want the editor to operate on. For example, the CHANGE 
subcommand can be entered: 

change/apple/pear/ 

The diagonal (/) delimits the character strings APPLE and PEAR. For the 
subcommands CHANGE, LOCATE, and DSTRING, the first nonblank character 
following the subcommand name (or its truncation) is considered the 
delimiter. No blank is reguired following the subcommand name. In the 
subcommand 

locate $vm/$ 

the dollar sign ($) is the delimiter. You cannot use a /in this case, 
since the diagonal is part of the character string you want to locate. 

When you enter these subcommands, you may omit the final delimiter, 
for example 

dstring/csect 

You must enter the final delimiter, however, when you specify a global 
change with the CHANGE subcommand. 

For the FIND and OVERLAY subcommands, additional blanks following the 
subcommand names are interpreted as arguments. The subcommand 

find Pudding 

reguests the editor to locate the line that has " Pudding" in columns 1 
through 9. Initial blanks are considered part of the character string. 

An asterisk, when used with an EDIT subcommand, may mean "to the end 
of the file" or "to the record length." For example, 
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delete* 
deletes all of the lines in a file, beginning with the current line. 

verify * 
indicates that the editor should display the entire length of records. 



?EDIT: 

When you make an error entering an EDIT subcommand, the editor displays 
the message 

?EDIT: line... 

where line... is the line, as you entered it, that the editor does not 
understand. 



The Current Line Pointer 

When you begin an editing session, a file is copied into virtual 
storage; in the case of a new file, virtual storage is acguired for the 
file you are creating. In either case, you can picture the file as a 
series of records, or lines; these lines are available to you, one at a 
time, for you to modify or delete. You can also insert new lines or 
records following any line that is already in the file. 

The line that you are currently editing is pointed to by the current 
line pointer. What you do during an editing session is: 

• Position the current line pointer to access the line you want to 
edit. 

• Edit the line: change character strings in it, delete it or insert 
new records following it. 

• Position the line pointer at the next line you want to edit. 

When you are editing a file and you issue an EDIT subcommand that 
either changes the position of the line pointer or that changes a line, 
the current line or the changed line (or lines) is displayed. You can 
also display the current line by using the TYPE subcommand: 

type 

If you want to examine more than one line in your file, you can use the 
TYPE subcommand with a numeric parameter. If you enter 

type 10 

the current line and the 9 lines that follow it are displayed; the line 
pointer then stays positioned at the last line that was displayed. 

You can move the line pointer up or down in your file. "Up" indicates 
a location toward the beginning of the file (the first record) ; "down" 
indicates a location toward the end of the file (the last record) . You 
use the EDIT subcommands UP and DOWN to move the line pointer up or down 
one or more lines. For example. 
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up 5 

moves the current line pointer to a line 5 lines closer to the beginning 
of the file, and 

down 

moves the pointer to point at the next sequential record in the file. 

You can also request that the line pointer be placed at the 
beginning, or top of the file, or at the end, or bottom of the file. 
When you issue the subcommand 

top 

you receive the message 

TOF: 

and the line pointer is positioned at a null line that is always at the 
top of the file. This null line exists only during your editing session; 
it is not filed on disk when you end the editing session. 

When you issue the subcommand 

bottom 

the current line pointer is positioned at the last record in the file. 
If you now enter input mode, all lines that you enter are appended to 
the end of the file. 

If the current line pointer is at the bottom of the file and you 
issue the DOWN subcommand, you receive the message 

EOF: 

and the current line pointer is positioned at the end-of-file, following 
the last record. 

When you are adding records to your file, the current line pointer is 
always pointing at the line you last entered. When you delete a line 
from a file, the line pointer moves down to point to the next line down 
in the file. 

Going from edit mode to input mode does not change the current line 
pointer. If you are creating a new file and, every 30 lines or so, you 
move the current line pointer to make corrections to the lines that you 
have entered, you must issue the BOTTOM subcommand to begin entering 
more lines at the end of the file. 

The current line pointer is also moved as the result of the LOCATE 
and FIND subcommands. You use the FIND subcommand to get to a line when 
you know the characters at the beginning of the line. For example, if 
you want to change the line 

BAXTER J.F. 065941 ACCNTNT 

you could first locate it by using the subcommand: 

find baxter 

If you do not know the first characters on a line, you can issue the 
LOCATE subcommand: 

locate /accntnt/ 
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Both of these subcommands work only in a top-to- bottom direction: you 
cannot use them to position the line pointer above the current line. If 
you use the FIHD or LOCATE subcommands and the target (the character 
string you seek) is not found, the editor displays a message, and 
positions the line pointer at the end of the file. Subsequently, if you 
reissue the subcommand, the editor starts searching at the top of the 
file. 

In a situation like that above, or in a case where you are 
repetitively entering the same LOCATE or FIND subcommand (if, for 
example, there are many occurrences of the same character string, but 
you seek a particular occurrence) you can use the = (REUSE) subcommand. 
To use the example above, you are looking for a line that contains the 
string ONCE UPON A TIME, but you do not know that it is above the 
current line. When you issue the subcommand: 

locate /once upon a time/ 

the editor does not locate the line, and responds: 

NOT FOUND 
EOF: 

if you enter 



the editor searches again for the same string, beginning this time at 
the top of the file, and locates the line: 

"ONCE UPOH A TIME" IS A COMMON 

This may still not be the line you are looking for. You can, again, 
enter: 



The LOCATE subcommand is executed again. This time, the editor might 
locate the line: 

A STORY THAT STARTED ONCE UPON A TIME 

Figure 5 illustrates a simple CMS file, and indicates how the current 
line pointer would be positioned following a sequence of EDIT 
subcommands. 

LINE-NUMBER EDITING: Some fixed-length files are suitable for editing by 
referencing line numbers instead of character strings. The EDIT 
subcommands that allow you to change the line pointer position by line 
number are discussed under "Line-Number Editing." 



Section 5. The CMS Editor 75 



CLP 
> 



EDIT PPRINT EXEC 

TOF: 

(null line) 

1 &CONTROL OFF 

2 SP = 
8IF .81 EQ . &EXIT 100 
8FN = 81 

&IF &1 EQ ? &GOTO -TELL 
&NFN = 8C0NCAT $ &1 
&IF .82 EQ . &EXIT 200 



3 
4 
5 
6 
7 

8 SFT = £2 

9 &FM = &3 
10 SIF .83 NE 



&SKIP 2 

11 &FM = A 

12 &SKIP 3 

13 8IF 83 NE ( &SKIP 2 

14 8FM = A 

15 &P = ( 

16 8C0NTR0L ALL 

17 COPY &FN &FT &FM &NFN SFT A ( UNPACK 

18 PRINT 8NFN &FT A SP &4 85 &6 87 88 89 &10 611 &12 813 814 

19 ERASE &NFN SFT A 

20 SEXIT 

21 -TELL &TYPE THIS EXEC PRINTS A LISTING FROM PACKED FORMAT 
EOF: 

The line numbers represented are symbolic: they are not an actual 
part of the file, but are used below to indicate at which line the 
current line pointer is positioned after execution of the EDIT 
subcommand indicated. 



Subcommand 

DOWN 5 

UP 

LOCATE /UNP/ 

TYPE 3 

BOTTOM 

DOWN 

FIND - 

TOP 

CHANGE /EQ/EQ/ 6 

DELETE 2 

INPUT * 



CLP Position 



> 

> 

> 

> 

> 





5 

4 

17 

19 



> 21 

> EOF: 

> 21 

> 

— > 5 

> 7 (lines numbered 5 and 6 are deleted) 

> the line just entered (between 7 and 8) 



Figure 5. Positioning the Current Line Pointer 



Verification and Search Columns 



There are two EDIT subcommands you can use to control what you and the 
editor "see" in a file. The VERIFY subcommand controls what you see 
displayed; the ZONE subcommand controls what columns the editor 
searches. Normally, when you edit a file, every reguest that you make 
of the editor results in the display of one or more lines at your 
terminal. If you do not want to see the lines, you can specify 

verify off 

Alternatively, if you want to see only particular columns in a file, you 
can specify the columns you wish to have displayed: 
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verify 1 30 

Some filetypes have default values set for verification, which 
usually include those columns in the file that contain text or data, and 
exclude columns that contain sequence numbers. If a verification column 
is less than the record length, you can specify: 

verify * 

to indicate that you want to see all columns displayed. 

In conjunction with the VERIFY subcommand, you can use the ZONE 
subcommand to tell the editor within which columns it can search or 
modify data. When you issue the subcommand 

zone 20 30 

The editor ignores all text in columns 1-19 and 31 to the end of the 
record when it searches lines for LOCATE, CHANGE, ALTER, and FIND 
subcommands. You cannot unintentionally modify data outside of these 
fields; you must change the zones in order to operate on any other 
data. 

The zone setting also controls the truncation column for records when 
you are using the CHANGE subcommand; for more details, see "Setting 
Truncation Limits." 



Changing, Deleting, and Adding Lines 

You can change character strings in individual lines of data with the 
CHANGE subcommand. A character string may be any length, or it may be a 
null string. Any of the characters on your terminal keyboard, including 
blanks, are valid characters* The following example shows a simple data 
line and the cumulative effect of CHANGE subcommands. 

ABC ABC ABC 

is the initial data line. 

CHANGE /ABC/XYZ/ 

changes the first occurrence of the character string "ABC" to the 
string "XYZ". 

XYZ ABC ABC 

CHANGE /ABC// 

deletes the character string "ABC" and concatenates the characters 
on each side of it. 

XYZ ABC 

CHANGE //ABC/ 

inserts the string "ABC" at the beginning of the line. 

ABCXYZ ABC 

CHANGE /XYZ /XYZ/ 

deletes one blank character following "XYZ". 

ABCXYZ ABC 
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CHANGE /C/C / 

adds a blank following the first occurrence of the character "C". 

ABC XYZ ABC 

is the final line. 

!£HE ALTER SUBCOMMAND: You can use the ALTER subcommand to change a 
single character; the ALTER subcommand allows you to specify a 
hexadecimal value so that you can include characters in your files for 
which there are no keyboard equivalents. Once in your file, these 
characters appear during editing as nonprintable blanks. For example, 
if you input the line 

IF A = B THEN 
in edit mode and then issue the subcommand 

alter = 8c 
the line is displayed: 

IF A B THEN 

If you subsequently print the file containing this line on a printer 
equipped to handle special characters, the line appears as 

IF A < B THEN 

since X'8C' is the hexadecimal value of the special character <. 

Either or both of the operands on the ALTER subcommand can be 
hexadecimal or character values. To change the X'8C' to another 
character, for example <, you could issue either 

alter 8c ae 

— or 

alter 8c < 

THE OVERLAY SUBCOMMAND: The OVERLAY subcommand allows you to replace 
characters in a line by spacing the terminal's typing element or cursor 
to a particular character position to make character -for-character 
replacements, or overlays. For example, given the line: 

ABCDEF 
the subcommand 

overlay xyz 
results in the line 

XYZDEF 

A blank entered on an OVERLAY line indicates that the corresponding 

character is not to be changed; to replace a character with a blank, use 

an underscore character (_) . Given the above line, XYZDEF, the 
subcommand 

overlay 3 

results in 

DE3 (The "D" is preceded by blanks in columns 1, 2, and 3.) 
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Global Changes 

You can make global, or repetitive changes, with the CHANGE and ALTER 
subcommands. On these subcommand lines, you can include operands that 
indicate: 

• The number of lines to be searched for a character or character 
string. An asterisk (*) indicates that all lines, from the current 
line to the end of the file, are to be searched. 

• Whether only the first occurrence or all occurrences on each line are 
to be modified. An asterisk (*) indicates all occurrences. If you do 
not specify an asterisk, only the first occurrence on any line is 
changed. 

For example, if you are creating a file that uses the (•) special 
character (X^F*) and you do not want to use the ALTER subcommand each 
time you need to enter the •. You could use the character -« as a 
substitute each time you need to enter a •. When you are finished 
entering input, move the current line pointer to the top of the file, 
and issue the global ALTER subcommand: 

top#alter -• af * * 

All occurrences of the character -* are changed to X'AF*. The current 
line pointer is positioned at the end of the file. 

When you use a global CHANGE subcommand, you must be sure to use the 
final delimiter on the subcommand line. For example, 

change /hannible/hannibal/ 5 

This subcommand changes the first occurrence of the string "HANNIBLE" on 
the current line and the four lines immediately following it. 

You can also make global changes with the OVERLAY subcommand, by 
issuing a REPEAT subcommand just prior to the OVERLAY subcommand. Use 
the REPEAT subcommand to indicate how many lines you want to be 
affected. For example, if you are editing a file containing the three 
lines 

A 
B 
C 

with the current line pointer at line "A", issuing the subcommands: 

repeat 3 

overlay | | | 

results in 

A I I I 
B I I I 
C I I I 

The current line pointer is now positioned at the line beginning with 
the character "C". 
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Deleting Lines 

You delete lines from a file with the DELETE subcommand; to delete more 
than one line, specify the number of lines: 

delete 6 

Or, if you want to delete all the lines from the current line to the end 
of the file, use an asterisk (*) : 

delete * 

If you want to delete an undetermined number of lines, up to a 
particular character string, you can use the DSTRING subcommand: 

dstring /weather/ 

When this subcommand is entered, all the lines from and including the 
current line down to and including the line just above the line 
containing the character string "WEATHER" are deleted. The current line 
pointer is positioned at the line that has "WEATHER" on it. 

If you want to replace a line with another line, you can use the 
REPLACE subcommand: 

replace ******* 

The current line is deleted and the line ••*******« is inserted in its 
place. The current line pointer is net moved. 

To replace an existing line with many new lines, you can issue the 
REPLACE subcommand with no new data line: 

replace 

The editor deletes the current line and enters input mode. 



Inserting Lines 

You can insert a single line of data between existing lines using the 
INPUT subcommand followed by the line of data you want inserted. For 
example 

input * this subroutine is for testing only 

inserts a single line following the current line. If you want to insert 
many lines, you can issue the INPUT subcommand to enter input mode. 

You can also add new lines to a file by using the GETFILE subcommand. 
This allows you to copy lines from other files to include in the file 
you are editing or creating. For example, 

getfile single items c 

inserts all the lines in the file SINGLE ITEMS C immediately following 
the current line pointer. The line pointer is positioned at the last 
line that was read in. 

You could also specify 

getfile double items c 10 25 
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to copy 25 lines, beginning with the tenth line, from the file DOUBLE 
ITEMS C. 

The $MOVE and $DUP EDIT macros provide two additional ways of adding 
lines into a file in a particular position. The $MOVE macro moves lines 
from one place in a file to another, and deletes them from their former 
position. For example, if you want to move 10 lines, beginning with the 
current line, to follow a line 9 lines above the current line, you can 
enter 

$move 10 up 8 

The $DUP macro duplicates the current line a specified number of 
times, and inserts the new lines immediately following the current 
line. For example, 

$dup 3 

creates 3 copies of the current line, and leaves the current line 
pointer positioned at the last copy. 



Describing Data File Characteristics 

Whe you issue the EDIT command to create a new file, the editor checks 
the filetype. If it is one of the reserved filetypes, the editor may 
assign particular attributes to it, which can simplify the editing 
process for you. The default attributes assigned to most filetypes are 
as follows: 

• Fixed-length, 80-character records 

• All alphabetic characters are translated to uppercase, regardless of 
how they are entered 

• Input lines are truncated in column 80 

• Tab settings are in columns 1, 6, 11, 16, 21, ... 51, 61, and so on, 
and the tab characters are expanded to blanks 

• Records are not serialized 

The filetypes for some CMS commands and for the language processors 
deviate from these default values. Some of the attributes assigned to 
files and how you can adjust them to suit your needs are discussed 
below. 



RECORD LENGTH 

You can specify the logical record length of a file you are creating on 
the EDIT command line: 

edit new file (lrecl 130 

If you do not specify a record length, the editor assumes the 
following defaults: 

• For editing old files, the existing record length is used. 

• For creating new files, the following default values are in effect: 



Section 5. The CMS Editor 81 



Filetype Record Length Format 

EXEC 80 characters Variable 

LISTING 121 characters Variable 

SCRIPT 132 characters Variable 

FREEFORT 81 characters Variable 

All others 80 Fixed 

If you edit a variable- length file and the existing record length is 
less than the default for the filetype, the record length is taken from 
the default value. 

When you use the LRECL option of the EDIT command you can override 
these default record lengths; you can also change the record lengths of 
existing files to make them larger, but not smaller. 

If you try to override the record length of an existing file and make 
it smaller, the editor displays an error message, and you must issue the 
EDIT command again with a larger record length. For example, suppose 
you have on your B-disk a file named MYFILE FREEFORT, which was created 
with the default record length of 81. If you try to edit that file by 
issuing: 

edit myfile freefort b (lrecl 72 

the editor displays the message: 

GIVE A LARGER RECORD LENGTH. 

You must then issue the EDIT command again and either specify a length 
of 81 or more, or allow it to default to the current record length of 
the file. 

You can use the COPYFILE command to increase or decrease the record 
length of a file before you edit it. For example, if you have 
fixed-length, 132-character records in a file, and you want to truncate 
all the records at column 80 and create a file with 80-character 
records, you could issue the command 

copyfile extra funds a (lrecl 80 



h.2H9. Jtecords 

The largest record you can edit with the editor is 160 characters. A 
file with record length up to 160 bytes (for example, a listing file 
created by a DOS program) can be displayed and edited. 

The largest record you can create with the CMS Editor, however, is 
130 characters using a 3270 display terminal and 134 characters using a 
typewriter terminal such as a 2741 or 1050. If you enter more than 130 
characters on a 3270, the record is truncated to 130 characters when you 
press the Enter key. If you type more than 134 characters on a line 
using a typewriter terminal, CP generates an attention interrupt to your 
virtual machine and the input line is lost when you press the Return 
key. 

For most purposes, you will not need to create records longer than 
130 characters. If it is necessary, however, you can expand a record 
that you have entered. You do this by issuing the CHANGE subcommand 
with operands, to add more characters to the record (for example, by 
changing a one-character string to a 31-character string) . 
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You cannot create a record that is longer than the record length of 
the file. For example, if the file you are editing has a default record 
length of 80, or if you specified LRECL 80 when you created the file, 
the editor truncates all records to 80 characters. 



I§£2Ed Length and File Size 



There is a relationship between the record length of a file and the 
maximum number of records it can contain. Figure 6 shows the 
approximate number of records, rounded to the nearest hundred, that the 
editor can handle in a virtual machine with different amounts of virtual 
storage. 

These numbers apply to a CMS virtual machine with only one accessed 
disk. 



| Virtual Machine Size 



Record 
Length 


I 

| 320K 


512K 


| 768K 


1024K 


80 Characters 


| 1700 
| 1100 


3800 


| 6800 


9800 


120 Characters 


2600 


| 4700 


6800 


132 Characters 


| 1100 


2400 


| 4300 
| 3600 


6200 


160 Characters 


| 900 


2000 


5100 



Figure 6. Number of Records Handled by the Editor 



RECORD FORMAT 



With the CMS Editor, you can create either fixed- or variable- length 
files. Except for the filetypes EXEC, LISTING, FREEFOBT, and SCRIPT, all 
the files you create have fixed-length records, by default. You can 
change the format of a file at any time during an editing session by 
using the RECFM subcommand: 

recfm v 

This changes the record format to variable-length. This does not change 
the record length; in order to add new records with a greater length, 
you must write the file onto disk and then reissue the EDIT command. 

The COPYFILE command also has an RECFM option, so that you can change 
the record format of a file without editing it. The command 

copy file * reguests a1 (recfm v trunc 

changes the record formats of all the files with a filetype of REQUESTS 
on your A-disk to variable- length. The TRUNC option specifies that you 
want trailing blanks removed from each of the records. 
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USING SPECIAL CHARACTERS 

The IMAGE and CASE subcommands control how data, once entered on an 
input line, is going to be represented in a file. The specific 
characters affected, and the subcommands that control their 
representation, are: 

• Alphabetic characters: CASE subcommand 

• Tab characters (X'05 1 ): IMAGE subcommand (ON and OFF operands) 

• Backspaces ('16'): IMAGE subcommand (CANON operand) 



!!E.h§l?etic Characters 

If you are using a terminal that has only uppercase characters, you do 
not need to use the CASE subcommand; all of the alphabetic characters 
you enter are uppercase. On terminals equipped with both uppercase and 
lowercase letters, all lowercase alphabetic characters are converted to 
uppercase in your file, regardless of how you enter them. If you are 
creating a file and you want it to contain both uppercase and lowercase 
letters you can use the subcommand 

case m 

The "M" stands for "mixed. " This attribute is not stored with the file 
on disk. If you create a new file, and you issue the CASE M subcommand, 
all the lowercase characters you enter remain in lowercase. If you 
subsequently file the file and later edit it again, you must issue the 
CASE M subcommand again to locate or enter lowercase data. 

There are two reserved filetypes for which uppercase and lowercase is 
the default. These are SCRIPT and MEMO, both of which are text or 
document-oriented filetypes. For most programming applications, you do 
not need to use lowercase letters. 



Tab Characters 

Logical tab settings indicate the column positions where fields within a 
record begin. These logical tab settings do not necessarily correspond 
to the physical tab settings on a typewriter terminal. What happens 
when you press the Tab key on a typewriter terminal depends on whether 
the image setting is on or off. The default for all filetypes except 
SCRIPT is IMAGE ON. You can change the default by issuing the 
subcommand 

image off 

If the image setting is on, when you press the Tab key the editor 
replaces the tab characters with blanks, starting at the column where 
you pressed the Tab key, and ending at the last column before the next 
logical tab setting. The next character entered after the tab becomes 
the first character of the next field. For example, if you enter 

tabset 1 15 

and then enter a line that begins with a tab character, the first data 
character following the tab is written into the file in column 15, 
regardless of the tab stop on your terminal. 
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If the image setting is off, the tab character, X'05 1 , is inserted in 
the record, just as any other data character is inserted. No blanks are 
inserted . 

If you want to insert a tab character (X'05 1 ) into a record and the 
image setting is on, you can do one of the following: 

1. Set IMAGE OFF before you enter or edit the record, and then use the 
Tab key as a character key. 

2. Enter some other character at the appropriate place in the record, 
and then use the ALTER subcommand to alter that character to a 
X«05«. 

SETTING TABS: When you create a file, there are logical tab settings in 
effect, so that you do not need to set them. The default values for the 
language processors correspond to the columns used by those processors. 
If you want to change them, or if you are creating a file with a 
nonreserved filetype, you may want to set them yourself. Use the TABSET 
subcommand, for example: 

tabset 1 12 20 28 72 

Then, regardless of what physical tab stops are in effect for your 
terminal, when you press the Tab key with image setting ON, the data you 
enter is spaced to the appropriate columns. 

The default tab settings used by the editor follow. 

Filetyjge £efault_Tab Settings 

ASSEMBLE, MACRO, 1, 10, 16, 31, 367 41, 46, 69, 72, 80, 

UPDATE, UPDTXXXX, 

ASM3705 

AMSERV 2, 6, 11, 16, 21, 26, 31, 36, 41, 46, 51, 61, 71, 80 

FORTRAN 1, 7, 10, 15, 20, 25, 30, 80 

FREEFORT 9, 15, 18, 23, 28, 33, 38, 81 

BASIC, VSBASIC 7, 10, 15, 20, 25, 30, 80 

PLIOPT, PLI 2, 4, 7, 10, 13, 16, 19, 22, 25, 31, 37, 43, 49, 55, 

79, 80 

COBOL 1, 8, 12, 20, 28, 36, 44, 68, 72, 80 

All Others 1, 6, 11, 16, 21, 26, 31, 36, 41, 46, 51, 61, 71, 81, 

91, 101, 111, 121, 131 

Note: When you are specifying tab settings for files, the first tab 
setting you specify should be the column in which you want your data to 
begin. The editor will not allow you to place data in a column preceding 
this one. For example, if you issue 

tabset 5 10 15 20 
and then enter an input line: 

input This is a line 
Columns 1, 2, 3, and 4 contain blanks; text begins in column 5. 



Section 5. The CMS Editor 85 



Backspaces 

For most of your applications, you do not need to underscore or 
overstrike characters or character strings. If you are using a 
typewriter terminal, and are typing files that use backspaces and 
underscores, you should use either the IMAGE OFF or IMAGE CANON 
subcommands so that the editor handles the backspaces properly. IMAGE 
CANON is the default value for SCRIPT files. 

CANON means that regardless of how the characters are keyed in 
(characters, backspaces, underscores) , the editor orders, or canonizes, 
the characters in the file as: character- backspace-underscore, 
character-backspace-underscore, and so on. If, for example, you want an 
input line to look like: 

ABC 
You could enter it as: 

ABC, 3 backspaces, 3 underscores 
- or - 

3 underscores, 3 backspaces, ABC 

A typewriter types out the line in the following order: 

A backspace, underscore 

B backspace, underscore 

C backspace, underscore, which results in: 

ABC 

If you need to modify a line that has backspaces, and you do not want 
to rekey all of the characters, backspaces, and overstrike characters in 
a CHANGE or REPLACE subcommand, you can use the ALTER subcommand to 
alter all of the backspaces to some other character and use a global 
CHANGE command. For example, the following seguences shows how to 
delete all of the backspace characters on a line: 

AAAAA 

alter 16 + 1 * 

_+A_+A_+A_+A_+A 

change /_+// 1 * 

AAAAA 

This technigue may also be useful on a display terminal. 



SETTING TRUNCATION LIMITS 

Every CMS file that you edit has a truncation column setting: this 
column represents the last character position in a record into which you 
can enter data, when you try to input a record that is longer than the 
truncation column, the record is truncated, and the editor sends you a 
message telling you that it has been truncated. 

You can change the truncation column setting with the TRUNC 

subcommand. For example, if you are creating a file with a record length 

of 80 and wish to insert some records that do not extend beyond column 
20, you could issue the subcommand 

trunc 20 
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Then, when you enter data lines, any line that is longer than 20 
characters is truncated and the editor sends you a message. If you are 
entering data in input mode, your virtual machine remains in input 
mode. 

When you use the CHANGE subcommand to modify records, the column at 
which truncation occurs is determined by the current zone setting. If 
you change a character string in a line to a longer string, and the 
resultant line extends beyond the current end zone, you receive the 
message 

TRUNCATED. 

If you need to create a line longer than the current end zone setting, 
use the ZONE subcommand to increase the setting. The subcommand 

zone 1 * 

extends the zone to the record length of the file. If the end zone 
already equals the record length, you have to write the file onto disk 
and reissue the EDIT subcommand specifying a longer record length. 

For most filetypes, the truncation and end zone columns are the same 
as the record length. For some filetypes, however, data is truncated 
short of the record length. The default truncation and end zone columns 
are: 

Filetype Column 

ASSEMBLE, MACRO 71~ 

UPDATE, 

UPDTxxxx 
AMSERV, COBOL, 72 

DIRECT, FORTRAN 

PLI, PLIOPT 

All other filetypes are truncated at their record length. 

You can, when creating files for your own uses, set truncation 
columns so that data does not extend beyond particular columns. 



ENTEBING A CONTINUATION CHARACTER IN COLUMN 72 

When you are using the editor to enter source records for an assembler 
language program and you need to enter a continuation character in 
column 72, or whenever you want to enter data outside a particular 
truncation setting, you can use the following technique: 

1. Change the truncation setting to 72, so that the editor does not 
truncate the continuation character: 

trunc 72 

2. Use the TABSET subcommand to set the left margin at column 72: 

tabset 72 

3. Use the OVERLAY subcommand to overlay an asterisk in column 72: 

overlay * 

Since the left margin is set at 72, the OVERLAY subcommand line 
results in the character * being placed in column 72. 
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4. Restore the editor truncation and tab settings: 

trunc 71 

tabset 1 10 16 31 36 41 51 61 71 81 

liote: If you issue the PRESERVE subcommand before you change the 
truncation and tab settings, then after you enter the OVERLAY 
subcommand, you can restore them with the RESTORE subcommand. See 
"Preserving and Restoring Editor Settings." 

y.§6 the $MARK Edit Macro: Another way to insert a continuation character 
is to use the $MARK edit macro. You can find out if the $MARK edit macro 
is available on your system by entering, in the CMS or CMS subset 
environment 

listfile $mark exec * 

If it is not available on your system, you can create the $MARK edit 
macro for your own use. See "Section 17. writing Edit Macros" in "Part 
3. Learning to Use EXEC." 

If you have the $MARK macro, then when you need to enter a 
continuation character, you can enter a null line to get into edit mode, 
issue the command 

$mark 

and then return to input mode to continue entering text. 



SERIALIZING RECORDS 

Some CMS files that you create are automatically serialized for you. 
This means that columns 73 to 80 of each record contain an identifier in 
the form: 

cccxxxxx 

where ccc are the first 3 characters of the filename and xxxxx is a 
sequence number. Sequence numbers begin at 00010 and are incremented by 
10. 

The filetypes that are automatically serialized in columns 73 to 80 
are: 

ASSEMBLE FORTRAN PLIOPT 

DIRECT COBOL UPDATE 

MACRO PLI UPDTXXXX 

You can serialize any file that has fixed-length, 80-character 
records by using the SERIAL subcommand: 

serial on 

The SERIAL subcommand can also be used to: 

• Assign a particular 3-character identifier: 

serial abc 
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• Specify that all 8 bytes of the sequence field be used to contain 
numbers: 

serial all 

• Specify a sequence increment other than 10: 

serial on 100 
— or — 
serial ccc 100 

• Indicate that no sequence numbers are to be assiqned to new records 
beinq inserted: 

serial off 

When you create a file or edit a file with sequence numbers, the 
sequence numbers are not written or updated until you issue a FILE or 
SAVE subcommand. Because the end verification columns for the filetypes 
that are automatically serialized are the same as their truncation 
columns, you do not see the serial numbers unless you specify 

verify * 

— or — 

verify 80 

Althouqh the serial numbers are not displayed while you edit the file, 
they do appear on your output listinqs or printer files. 

If you are editinq files with the followinq filetypes: 

BASIC 

VSBASIC 

FREEFOET 

the sequence numbers are on the left. For BASIC and VSBASIC files, 
columns 1-5 are used; numbers are blank-padded to the left. For 
FREEFORT files, the sequence numbers use columns 1-8, and are 
zero-padded to the left. To edit these files, you should use line-number 
editinq, which is discussed next. 

LINE-NUMBER EDITING 

To edit a file by line numbers means that when you are addinq new lines 
to a file or referencinq lines that you wish to chanqe, you refer to 
them by their line, or sequence numbers, rather than by character 
strinqs. You can use line-number editinq only on files with 
f ixed-lenqth, 80-character records. 

If you want to edit by line numbers, issue the subcommand 

linemode riqht 

— or — 

linemode left 

where "riqht" indicates that the sequence numbers are on the riqht, in 
columns 76-80, and "left" indicates you want sequence numbers on the 
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left in columns 1-5. LINEMODE LEFT is the default for BASIC, VSEASIC, 
and FREEFORT files. You do not have to specify it. You must specify 
LINEMODE for files with other filetypes. 

If you specify LINEMODE RIGHT to use line-number editing on a 
typewriter terminal, the line numbers are displayed on the left, as a 
convenience, while you edit the file. 

When you are using line-number editing in input mode, you are 

prompted to enter lines; the line numbers are in increments of 10. For 

example, when you are creating a new file, you are prompted for the 
first line number as follows: 

10 

On a typewriter terminal, you enter your input line following the 10. 
When you press the carriage return, you are prompted again: 

20 

and you continue entering lines in this manner until you enter a null 
line. 

You can change the prompting increment to a larger or smaller number 
with the PROMPT subcommand: 

prompt 100 

When you are in edit mode you can locate a line by giving its line 
number: 

700 

This is the nnnnn subcommand. In line-number editing, you use it instead 
of the INPUT subcommand to insert a single line of text. For example, 

905 x = a * b 

inserts the text line "X = A * B" in the proper sequence in the file. 
If you use "nnnnn text" specifying the number of a line that already 
exists, that line is replaced; the current line pointer is moved to 
point to it. 

The EDIT subcommands that you normally use for context editing, such 
as CHANGE, ALTER, LOCATE, UP, DOWN, and so forth, can also be used when 
you are line-number editing; their operation does not change. 



When you are using line-number editing, the editor uses the prompting 
increment set by the PROMPT subcommand. However, when you begin adding 
lines of data between existing lines, the editor uses an algorithm to 
select a line number between the current line number and the next line 
number. If a prompting number cannot be generated because the current 
line number and the next line number differ only by one, the editor 
displays the message 

RENUMBER LINES 

and you must resequence the line numbers in the file before you can 
continue line-number editing. 
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You can resequence the line numbers in one of three ways: 

1. If you are a VSBASIC, BASIC, or FREEFORT user, you must use the 
RENUM subcommand: 

renum 

This subcommand resolves all references to lines that are 
renumbered. 

2. If you are using right-handed line-number editing, you must 

a. Turn off line-number editing: 

linemode off 

b. If you want to change the 3-character identifier or specify 
8-character seguence numbers, issue the SERIAL subcommand, for 
example: 

serial all 

If you want to use the default serialization setting, you do not 
need to issue the SERIAL subcommand. 

c. Issue the SAVE subcommand: 

save 

d. Reissue the LINEMODE subcommand and continue line-number 
editing: 

linemode right 

3. If you are using left-handed line-number editing for a filetype 
other than VSBASIC, BASIC, or FREEFORT, you must manually change 
individual line numbers using EDIT subcommands. In order to modify 
the line numbers, you must change the zone setting and the tab 
setting: 

zone 1 * 
tabset 1 6 

so that you can place data in columns 1 through 6. 

When you are using right-handed line-number editing, and a FILE, 
SAVE, or automatic save request is issued, the editor does not 
resequence the serial numbers, but displays the message 

RESERIALIZATION SUPPRESSED 

so that the lines numbers that are currently saved on disk match the 
line numbers in the file. You must cancel line-number editing (using the 
LINEMODE OFF subcommand) before you can issue a FILE or SAVE subcommand 
if you want to update the seguence numbers. 



Controlling the Editor 

There are a number of EDIT subcommands that you can use to maximize the 
use of the editor in CMS. A few techniques are suggested here; as you 
become more familiar with VM/370 and CMS you will develop additional 
techniques for your own applications. 
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COMMUNICATING WITH CMS AND CP 

Often during a terminal session, you may need to issue a CMS command or 
a CP command. You can issue certain CMS commands and most CP commands 
without terminating the edit session. The EDIT subcommand CMS places 
your virtual machine in the CMS subset mode of the editor, where you can 
issue CHS commands that do not modify your virtual storage. Remember 
that the editor is using your virtual storage; if you overlay it with 
any other command or program, you will not be able to finish your 
editing. 

One occasion when you may want to enter CMS subset is when you want 
to issue a GETFILE subcommand for a file on one of your virtual disks 
and you have not accessed the disk. You can enter: 

cms 
the editor responds: 

CMS SUBSET 

and you can enter 

access 193 b/a 

return 

get setup script b 

The special CMS SUBSET command RETURN returns your virtual machine to 
edit mode. 

You can enter CP commands from CMS subset, or you can issue them 
directly from edit mode or input mode with the #CP function. For 
example, if you are inputting lines into a file and another user sends 
you a message, you can reply without leaving input mode: 

#cp m oph i will call you later 

If you enter #CP without specifying a command line, you receive the 
message 

CP 

which indicates that your virtual machine is in the CP command 
environment, and you can issue CP commands. You would not, however, 
want to issue any CP command that would modify your virtual storage or 
alter the status of the disk on which you want to write the file. 

To return to edit or input mode from CP, use the CP command, BEGIN. 



CHANGING FILE IDENTIFIERS 

There are several methods you can use to change a file identifier before 
writing the file onto disk. You can use the FNAME and FMODE subcommands 
to change the filename or filemode, or you can issue a FILE or SAVE 
subcommand specifying a new file identifier. 

For example, if you want to create several copies of a file while you 
are using the editor, you can issue a series of FNAME subcommands, 
followed by SAVE subcommands, as follows: 
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edit test file 
EDIT: 



fn test1#save 



fn test2#save 



fn test3#file 
Or, you could issue the SAVE and FILE subcommands as follows 
edit test file 



save testl 



save test2 



file test3 

In both of the preceding examples, when the FILE subcommand is executed, 
there are files named TEST FILE, TEST1 FILE, TEST2 FILE, and TEST3 FILE. 
The original TEST FILE is unchanged. 

To change the filemode letter of a disk, use the FMODE subcommand. 
You can do this in cases where you have begun editing a file that is on 
a read-only disk, and want to write it. Since you cannot write a file 
onto a read-only disk, you can issue the FMODE subcommand to change the 
mode before filing it : 

fmode a 
file 

Or, you can use the FILE (or SAVE) subcommand specifying a complete file 
identifier: 

file test file a 

You should remember, however, that when you write a file onto disk, 
it replaces any existing file that has the same identifier. The editor 
does not issue any warning or informational messages. If you are 
changing a file identifier while you are editing the file, you must be 
careful that you do not unintentionally overlay existing files. To 
verify the existence of a file, you can enter CMS subset and issue the 
STATE or LISTFILE commands. 



CONTROLLING THE EDITOR'S DISPLAYS 



When you are using a typewriter terminal, you may not always want to see 
the editor verify the results of each of your subcommands. Particularly 
when you are making global changes, you may not want to see each line 
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displayed as it is changed. You can issue the VERIFY subcommand with 
the OFF operand to instruct the editor not to display anything unless 
specifically requested. After you issue 

verify off 

lines that are normally displayed as a result of a subcommand that moves 
the current line pointer (UP, DOWN, TOP, BOTTOM, and so forth), or that 
changes a line (CHANGE, ALTER, and so forth), are not displayed. If the 
current line pointer moves to the end of the file, however, the editor 
always displays the EOF: message. 

If you are editing with verification off, then you must be 
particularly careful to stay aware of the position of your current line 
pointer. You can display the current line at any time using the TYPE 
subcommand : 

type 

k°H3 and Short Error Messages: When you enter an invalid subcommand 
while you are using the editor, the editor normally responds with the 
error message 

?EDIT: line... 

displaying the line that it did not recognize. If you prefer, you can 
issue the SHORT subcommand so that instead of receiving the long form of 
the error, you receive the short form, which is: 



When you issue an invalid edit macro request (any line that begins with 
a $) , you receive the message 



To resume receiving the long form of the error message, use the LONG 
subcommand: 

long 

LONG and SHORT control the display of the error message regardless of 
whether you are editing with verification on or off. 



PRESERVING AND RESTORING EDITOR SETTINGS 

The PRESERVE and RESTORE subcommands are used together; the PRESERVE 
subcommand saves the settings of the EDIT subcommands that control the 
file format, message and verification display, and file identifier. If 
you are editing a file and you want to temporarily change some of these 
settings, issue the PRESERVE subcommand to save their current status. 
When you have finished your temporary edit project, issue the RESTORE 
subcommand to restore the settings. 

For example, if you are editing a SCRIPT file and want to change the 
image setting to create a particular format, you can enter: 

preserve 

image on 

tabset 1 15 40 60 72 

zone 1 72 

trunc 72 
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When you have finished entering data using these settings, you can issue 
the subcommand 

restore 

to restore the default settings for SCRIPT filetypes. 



X, Y, = , ? SUBCOMMANDS 

The X, Y, = , and ? subcommands all perform very simple functions that 
can help you to extend the language of the CMS Editor. They allow you 
to manipulate, reuse, or interrogate EDIT subcommands. 

If you have an editing project in which you have to execute the same 
subcommand a number of times, you can assign it to the X or Y 
subcommands, as follows: 

x locate /insert here/ 
y getfile insert file c 

Each time that you enter the X subcommand: 

x 

the command line LOCATE /INSERT HERE/ is executed, and every time you 
enter the Y subcommand: 

y 

the GETFILE subcommand is executed. 

When you specify a number following an X or Y subcommand, the 
subcommand assigned to X or Y is executed the specified number of times, 
for example 

x locate /aa/ 
x 10 

the LOCATE subcommand line is executed 10 times before you can enter 
another EDIT subcommand. 

Another method of re-executing a particular subcommand is to use the 
= (REUSE) subcommand. For example, if you enter 

locate /ard/ 
AARDVARK 



the LOCATE subcommand is re-executed 7 times. 

What the = (REUSE) subcommand actually does is to stack the 
subcommand in the console stack. Since CMS, and the editor, read from 
the console stack before reading from the terminal, the lines in the 
stack execute before a read request is presented to the terminal. When 
you enter multiple egual signs, the subcommand is stacked once for each 
equal sign you enter. 

You can also stack an additional EDIT subcommand following an egual 
sign. The subcommand line is also stacked, but it is stacked LIFO 
(last-in, first-out) so that it executes before the stacked subcommand. 
For example, if you enter: 
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delete 
= next 

a DELETE subcommand is executed, then a DELETE subcommand is stacked, 
and a NEXT subcommand is stacked in front of it. Then the stacked lines 
are read in and executed. The above sequence has the same effect as if 
you enter 

delete 

next 

delete 

In addition to stacking the last subcommand executed, you can also 
find out what it was, using the ? subcommand. For example, if you enter 

next 10 
7 

the editor displays 

NEXT 10 

Since the subcommand line NEXT 10 was the last subcommand entered, if 
you enter an = subcommand, it is executed again. You cannot stack a ? 
subcommand. 

Note: The ? subcommand, on a display terminal, copies the last EDIT 
subcommand into the user input area, where you may modify it before 
re-entering it. 



WHAT TO DO WHEN YOU HUN OUT OF SPACE 

There are two situations that may prevent you from continuing an edit 
session or from writing a file onto disk. You should be aware of these 
situations, know how to avoid them, and how to recover from them, should 
they occur. 

When you issue the EDIT command to edit a file, the editor copies the 

file into virtual storage. If it is a large file, or you have made many 

additions to it, the editor may run out of storage space. If it does, it 
issues the message: 

AVAILABLE STORAGE IS NOW FULL 

When this happens, you cannot make any changes or additions to the file 
unless you first delete some lines. If you attempt to add a line, the 
editor issues the message 

NO BOOH 

If you were entering data in input mode, your virtual machine is 
returned to edit mode, and you may receive the message 

STACKED LINES CLEARED 

which indicates that any additional lines you entered are cleared and 
will not be processed. 

You should use the FILE subcommand to write the file onto disk. If 
you want to continue editing, you should see that the editor has more 
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storage space to work with. To do this, you can find out how large your 
virtual machine is and then increase its size. To find out the size, 
issue the CP QUERY command: 

cp query virtual storage 

If the response is 

STORAGE = 256K 

You might want to redefine your storage to 512K. Use the CP command 
DEFINE, as follows: 

cp define storage 512k 

This command resets your virtual machine, and you must issue the CP IPL 
command to reload the CMS system before you can continue editing. 

If a file is very large, the editor may not have enough space to 
allow you to edit it using the EEIT command. The message 

DMSEDI132S FILE «fn ft fm« TOO LARGE 

indicates that you must obtain more storage space before you can edit 
the file. If this is the case, or if you are editing large files, you 
should redefine your storage before beginning the terminal session. If 
this happens consistently, you should see your installation support 
personnel about having the directory entry for your userid updated so 
that you have a large storage size to begin with. 



Splitting CMS Files into Smaller Files 



If the file you are editing is too large, and the data it contains does 
not have to be in one file, you can split the file into smaller files, 
so that it is easier to work with. Two of the methods you can use to do 
this are described below. 

2S§ the COPYFILE Command: You can use the COPYFILE command to copy 
portions of a file into separate files, and then delete the copied lines 
from the original file. For example, if you have a file named TEST FILE 
that has 1000 records, and ybu want to split it into four files, you 
could enter: 

copyfile test file a testl file a (fromrec 1 for 250 

copyfile test file a test2- file a (fromrec 251 for 250 

copyfile test file a test3i file a (fromrec 501 for 250 

copyfile test file a test4 file a (fromrec 751 for 250 

When these COPYFILE commands are complete, you have four files 
containing the information from the original TEST FILE, which you can 
erase: 

erase test file 

H§5 the Editor: If you use the editor to create smaller files, you can 
edit them as you copy them, that is, if you have other changes that you 
want to make to the data. To copy files with the editor, you use the 
GETFILE subcommand. Using the file TEST FILE as an example, you might 
enter: 
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edit testl file 

getfile test file a 1 250 



file 

edit test2 file 

getfile test file a 251 250 



Again, you could erase the original TEST FILE when you are through with 
your edit session. 



When Your Disk Is Full 



Hhen you enter a FILE or SAVE subcommand or when an automatic save 
reguest is issued, the editor writes a copy of the file you are editing 
onto disk, and names it EDIT CMSUT1. If this causes the disk to become 
full, you receive the message 

DMSBWR170S DISK 'raode(cuu)' IS FULL 

The editor erases the workfile, and issues the message 

SET NEW FILEMODE, OB ENTER CMS SUBSET AND CLEAR SOME SPACE 

The original file (as last written onto disk) remains unchanged. You 
can use the CMS subcommand to enter CMS subset, and erase any files that 
you do not need. You can use the LISTFILE command to list the files on 
the disk, then the ERASE command to erase the unwanted files. 

If you cannot erase any of the file on the disk, there are several 
alternate recovery paths you can take: 

1. If you have another read/write disk accessed, you can use the FMODE 
subcommand to change the filemode of the file, so that when you 
file it, it is written to the other disk. If you have a read/write 
disk that is not accessed, you can access it in CMS subset. After 
filing the file on the second disk, erase the original copy, and 
then use the COPYFILE command to transfer the file back to its 
original disk. 

2. If you do not have any other read/write disk in your virtual 
machine, you may be able to transfer some of your files to another 
user, using the PUNCH or DISK DUMP commands in CMS subset. When the 
files have been read onto the other user's disk, you can erase them 
from your disk. Then, return to edit mode and issue the FILE 
subcommand. 

3. In CMS subset, erase the original disk file (if it existed), then 
return to edit mode and file the copy that you are editing. You 
should not use this method unless absolutely necessary, since any 
unexpected problems may result in the loss of both the disk file 
and the copy. 

After you use the FILE subcommand to write the file onto disk, you 
should continue erasing any files you no longer need. 
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Summary of EDIT Subcommands 

The EDIT subcommands, and their formats, are shown in Figure 7. Refer to 
the VM/370: CMS Command and Macro Reference for complete details. 



| Subcommand Format | Function | 

I r -i 1 Scans the next n records of | 
| ALter charl char2 | n r t I |the file, altering the speci- | 
I | * | G | | |fied character, either once in | 
| I 1 I * I I |each line or for all occur- | 
1 t l j j jrences in the line. | 


I r t | Automatically saves the file | 
| AUTOsave |n | | on disk after the indicated | 
I IOIJM Inumber of lines have been | 
I «- J Iprocessed. I 

I r i IPoints the current line | 
| BAckward | n| I pointer to a line above the | 
| 1 Jl |line currently pointed to. | 

| L J | | 


| Bottom |Makes the last line of the | 
I | f ile the current line. | 


I r i 1 Indicates whether translation | 
I CASE | M | |to uppercase is to be done, or| 
I | U | | displays the current status. | 

| L J 1 1 


| i- r m |Changes string 1 to string2 for| 
I Change [/string 1[ /string2[ / jn |G||]]]|n records or to EOF, either | 
| (J l*ll | for the first occurrence in | 
| l l jj j each line or for all | 
| I occurrences. | 


| CMS |Enters CMS subset command | 
| | mode. | 


I r -i. | Deletes n lines or to the end | 
j DELete | n | I of the file (*) . j 
I I * I I I 
till I I 

| L J | | 

I r i IPoints to the nth line from | 
I DOwn j n | | the current line. | 
1 1 J 1 1 1 

| L J | | 

| DString /[string [/]] | Deletes all lines from the | 
| | current line down to the line | 
| [containing the indicated | 
| | string. I 


I FILE [fn [ft [fm]]] | Saves the file being edited on | 
| |disk or changes its identi- | 
| Ifiers. Returns to CMS. | 



I 



Figure 7. Summary of EDIT Subcommands and Macros (Part 1 of 4) 
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I Subcommand Format | Function | 

I Find [line] I Searches the file for the | 
I Igiven line. I 


| FHode [fm] IResets or displays the | 
I Ifilemode. I 


| FName [fn] IResets or displays the | 
I Ifilename. I 

I FORMat /DISPLAY I ISwitches the 3270 terminal | 
I \ LINE J | between display mode and line | 
| |mode. (3270 only) | 

I r t IPoints to the nth line after | 
I FOrward | n | | the current line. | 
1 1 J 1 1 1 

| L J | | 


| r r rri-i-i-i |Inserts a portion or all of | 
| Getfile fn | ft | fm | m | n | | | | (the specified file after the | 
1 1 1 111*1111 (current line. I 

| LLLLJJJJ| | 


| r i | Expands text into line images j 
I IMAGE |0N | I or displays current settings. | 
1 IOFF | I I 
| | CANON | | I 

| L J | | 


| Input [line] llnserts a line in the file or | 
| I enters input mode. | 


| r i I Sets or displays current | 
| LIMEmode (LEFT | |setting of line—number | 
| |RIGHT| I editing. I 
1 (OFF | | I 

| L J | | 


| [ Locate ]/[ string [/]] I Scans file from next line for | 
| | first occurrence of "string*. | 


| LONG | Enters long error message | 
| Imode. I 

| r t IPoints to the nth line down | 
I Next j n | jfrom the current line. | 
1 1 J 1 1 1 

| L J | | 


| Overlay [line] | Replaces all or part of the | 
| I current line. I 


I PREserve | Saves current mode settings. | 


| r -i I Sets or displays line number | 
| PROMPT |n | | increment. Initial setting is | 
1 IIOI 110. I 
j t j 1 1 



Figure 7. Summary of EDIT Subcommands and Macros (Part 2 of 4) 
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Subcommand Format 



Function 



QUIT 






(Terminates edit session with 
| no updates incorporated since 
|last save request. 


r l 

RECfm | F | 
1 V | 

L J 






|Sets or displays record format 
(for subsequent files. 


r 
RENum |strtno 

110 


r n 
| incrno| | 
|strtno| I 

L J J 




| Recomputes line numbers for 
IVSBASIC and FREEFORT source 
| files. 


r t 

REPEAT | n | 

1 * 1 
1 I 1 

L J 







| Executes the following OVERLAY 
(subcommand n times. 


Replace [line 


] 


| Replaces the current line or 
I deletes the current line and 
| enters input mode. 


REStore 






| Restores Editor settings to 
lvalues last preserved. 


RETURN 






IReturns to edit environment 
(from CMS subset. 


(REUSE \ [subcommand] 




| Stacks (LIFO) the last EDIT 
(subcommand that does not start 
| with REUSE or the question 
|mark (?) and then executes any 
(given EDIT subcommand. 


SAVE [fn [ft 


[fn]]] 




| Saves the file on disk and 
| stays in edit environment. 


/SCroll 
\S[croll]U[p] 


r t 

I in I 

/ 1* 1 

11 1 

L J 




(Displays a number of screens 
| of data above or below the 
leurrent line (3270 only) . 


SERial / OFF 
) ON 
\ ALL 
' seq 


liner | f 

1 15 J j 




| Turns serialization on or off 
|in columns 73 through 80. 


SHORT 






| Enters short error message 
|mode. 


r i 
STACK | n | 

1 J 1 
1 | 
(subcommand | 

L J 




IStacks data lines or EDIT 
(subcommands in the console 
| input stack. 



I 



—J 



Figure 7. Summary of EDIT Subcommands and Macros (Part 3 of U) 
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Subcommand Format 
TABSet n1 [ n2 ... nn ] 
TOP 



r t 

TRUNC | n | 

I * I 

L J 



r r 11 

Type | m | n | | 

I J I * I I 
1*1 II 

L L J J 



Function 

|Sets logical tab stops 

Moves the current line pointer 
to the null line at the top 
of the file. 

Sets or displays the column of 
truncation. An asterisk (*) 
indicates the logical record 
length. 

Displays m lines beginning 
with the current line. Each 
line may be truncated to n 
characters. 



r t 

Up I n | 

I 1 I 

L J 



r t 

Verify |0N | 
| OFF | 

L J 



rr t t 

I | started lendcol | 

111 1*1 

LL J J 



m 



r n 

(subcommand | 
I n | 

I I I 

L J 



r r t t 

Zone | m | n | | 

111*11 
1*1 II 

L L J J 



Jnnnnn ) 
|nnnnnnnn J 



[text] 



r i 
$DUP | n | 

I J I 

L J 

$MOVE n 



Up m 
Down m 
TO label 



Moves the current line pointer 
toward the top of the file. 



Sets, displays, or resets 
verification. An asterisk (*) 
indicates the logical record 
length. 

Assigns to X or Y the given 
EDIT subcommand or executes 
the previously assigned 
subcommand n times. 



Sets or displays the columns 
between which editing is to 
take place. 



Displays the last EDIT 
subcommand, except = or ?. 

Locates the line specified by 
the given line number and 
inserts text, if given. 

Duplicates the current line n 
times. $DUP is an edit macro. 



Moves n lines up or down m 
lines. $MOVE is an edit macro. 



Figure 7. Summary of EDIT Subcommands and Macros (Part 4 of 4) 
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Section 6. Introduction to the EXEC Processor 



An EXEC is a CMS file that contains executable statements. The 
statements may be CMS or CP commands or EXEC control statements. The 
execution can be conditionally controlled with additional EXEC 
statements, or it may contain no EXEC statements at all. In its simplest 
form, an EXEC file may contain only one record, have no variables, and 
expect no arguments to be passed to it. In its most complex form, it can 
contain thousands of records and may resemble a program written in a 
high-level programming language. As a CMS user, you should become 
familiar with the EXEC processor and use it often to tailor CMS commands 
to your own needs, as well as to create your own commands. 

The following is an example of a simple EXEC procedure that might be 
named RDLINKS EXEC: 

CP LINK DEWEY 191 291 RR DEWEY 
CP LINK LIBRARY 192 292 RR DEWEY 
ACCESS 291 B/A 
ACC 292 C/A 

When you enter 

rdlinks 

each command line contained in the file RDLINKS EXEC is executed. 

You could also create an EXEC procedure that functions like a 
cataloged procedure, and set it up to receive an argument, so that it 
executes somewhat differently each time you invoke it. For example, a 
file named ASM EXEC contains the following: 

ASSEMBLE &1 
PRINT 81 LISTING 
LOAD &1 
START 

If you invoke the EXEC specifying the name of an assembler language 
source file, such as 

asm myprog 

the procedure executes as follows: 

ASSEMBLE MYPROG 
PRINT MYPROG LISTING 
LOAD MYPROG 
START 

The variable &1 in the EXEC file is substituted with the argument you 
enter when you execute the EXEC. As many as 30 arguments can be passed 
to an EXEC in this manner; the variables thus set range from &1 through 
£30. 



CREATING EXEC FILES 

EXEC files can be created with the CMS Editor, by punching cards, or by 
using CMS commands or programs. When you create a file with the editor. 
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records are, by default, variable-length with a logical record length of 
80 characters. EXEC can process variable length files of up to 130 
characters. To can create a variable-length EXEC file larger than 80 
characters, use the LRECL option of the EDIT command: 

edit new exec a (Irecl 130 

To convert a variable-length file to a fixed-length file, you can 
edit the EXEC file and issue the subcommand 

recfm f 

Or, you can use the COPYFILE command: 

copyfile old exec a (recfm f 

If you use fixed-length EXEC files, you should be aware that the EXEC 
interpreter only processes the first 72 characters of each record in a 
fixed-length file, regardless of the record length. You can, however, 
enter command or data lines that are longer than than 72 characters to 
be processed by using the SBEGSTACK, SBEGTYPE, SBEGPUNCH, and SBEGEMSG 
control statements preceding the line(s) you want to be processed. If 
you specify &BEGPUNCH ALL, EXEC processes lines up to 80 characters 
long; if you specify SBEGTYPE ALL, &BEGSTACK ALL, or &BEGEMSG ALL, EXEC 
processes lines up to 130 characters. 

In variable-length EXEC files, there are no such restrictions; lines 
up to 130 characters are processed in their entirety. 

Two CMS commands create EXEC files. One is LISTFILE, which can be 
invoked with the EXEC option; it creates a file named CMS EXEC. The uses 
of CMS EXEC files are discussed under the heading "CMS EXECs and How To 
Use Them." The CMS/DOS command LISTIO creates an EXEC file named 
SLISTIO EXEC, which creates records for each of the system and 
programmer logical unit assignments. The LISTIO command and the $LISTIO 
EXEC are described in "Section 9. Developing DOS Programs Under CMS." 



INVOKING EXEC FILES 

EXEC procedures are invoked when you enter the filename of the EXEC 
file. You can precede the filename on the command line with the CMS 
command, EXEC. For example: 

exec test type list 

where TEST is the filename of the EXEC file and TYPE and LIST are 
arguments (81, £2, and so on) you are passing to the EXEC. For example, 
an EXEC named PREPEDIT would be executed when you entered either: 

prepedit newfile replace 

— or — 

exec prepedit newfile replace 

You must precede the EXEC filename with the EXEC command when: 

• You invoke an EXEC from within another EXEC. 

• You invoke an EXEC from a program. 

• You have the implied EXEC function set off for your virtual machine. 
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The implied EXEC function is controlled by the SET command. If you 
issue the command 

set impex off 

then you must use the EXEC command to invoke an EXEC procedure. The 
default setting is ON; you almost never need to change it. 

There is one EXEC file that you never have to specifically invoke. 
This is a PROFILE EXEC, which is automatically executed after you load 
CHS, when your A-disk is accessed. PROFILE EXECs are discussed next. 



PROFILE EXECs 

A PROFILE EXEC must have a filename of PROFILE. It can contain the CP 
and CHS commands you normally issue at the start of every terminal 
session. For example: 

• Commands that describe your terminal characteristics, such as 

CP SET LIHEDIT OH 
SET BLIP * 
SET RDYHSG SHSG 
SYNONYH HYSYN 

• Commands that spool your printer and punch for particular classes or 
characteristics: 

CP SPOOL E CLASS S HOLD 

• Commands to initialize macro and text libraries that you commonly 
use: 

GLOBAL HACLIB OSHACRO CHSLIB 
GLOBAL TXTLIB PRIVLIB 

• Commands to access disks that are a permanent part of your 
configuration : 

ACCESS 196 B 

A PROFILE EXEC file that contains all of these commands might look 
like this: 

SCOHTROL OFF 

CP SET LIHEDIT ON 

CP SPOOL E CLASS S HOLD 

SET RDYHSG SHSG 

SET BLIP * 

SYNOHYH HYSYH 

GLOBAL HACLIB OSHACRO CHSLIB 

GLOBAL TXTLIB PRIVLIB 

ACCESS 196 B 

6C0NTR0L OFF is an EXEC control statement that specifies that the CP 
and CHS command lines are not to be displayed on your terminal before 
they execute. 

A PROFILE EXEC can be as simple or as complex as you reguire. As an 
EXEC file, it can contain any valid EXEC control statements or CHS 
commands. The only thing that makes it special is its filename, 
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PEtOFILE, which causes it to be executed the first time you press the 
Return key after loading CMS. 



EXECUTING YOUR PROFILE EXEC 

Usually, the first thing you do after loading CMS is to type a CMS 
command. When you press the Return key to enter this command or if you 
enter a null line, CMS searches your A-disk for a file with a filename 
of PROFILE and a filetype of EXEC. If such a file exists, it is 
executed before the first CMS command you enter is executed. Because 
you do not do anything special to cause your PROFILE EXEC to execute, 
you can say that it executes "automatically." 

You can prevent your PROFILE EXEC from executing automatically by 
entering 

access (noprof) 

as the first CMS command after you IPL CMS. You can enter: 

profile 

at any time during a CMS session to execute the PROFILE EXEC, if you had 
accessed your A-disk without it, or if you had made changes to it and 
wanted to execute it, or if you had changed your virtual machine and 
wanted to restore its original characteristics. 



CMS EXECs and How To Use Them 

A file named CMS EXEC is created when you use the EXEC option of the 
LISTFILE command, for example 

listfile pr* document a (exec 

The usual display that results from this LISTFILE command is a list of 
all the files on your A-disk with a filetype of DOCUMENT that have 
filenames beginning with the characters "PR". CMS, however, creates a 
CHS EXEC file that contains a record for each file that would be listed. 
The records are in the format: 

61 62 filename filetype filemode 

Column 1 is blank. Now, if you have the following files on your A-disk: 

PRFILE1 DOCUMENT 

PRFILE2 DOCUMENT 

PRFILE3 DOCUMENT 

PRFILE4 DOCUMENT 

The CMS EXEC file would contain the records: 



61 


62 


PRFILE1 


DOCUMENT 


A1 


61 


62 


PRFILE2 


DOCUMENT 


A1 


61 


62 


PRFILE3 


DOCUMENT 


A1 


61 


62 


PRFILE4 


DOCUMENT 


A1 
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In the preceding lines, 81 and 82 are variables that can receive values 
from arguments you pass to the EXEC when you execute it. For example, 
if you execute this CMS EXEC by issuing: 

cms disk dump 

the EXEC interpreter substitutes, on each line, the variable 81 with the 
DISK and the variable 82 with DUMP and executes the commands: 

DISK DUMP PRFILE1 DOCUMENT A1 

DISK DUMP PRFILE2 DOCUMENT A1 

DISK DUMP PRFILE3 DOCUMENT A1 

DISK DUMP PRFILE4 DOCUMENT A1 

You can use this technigue to transfer a number of files to another 
user. You should remember to spool your punch with the CONT option 
before you execute the EXEC, so that all of the files are transferred as 
a single spool file, for example: 

cp spool d cont library 

then, after executing the EXEC file, close the punch: 

cp spool d nocont close 

If you pass only one argument to your CMS EXEC file, the variable 82 
is set to a null string. For example, 

cms erase 

executes as 

ERASE PRFILE1 DOCUMENT A1 

ERASE PRFILE2 DOCUMENT Al 

ERASE PRFILE3 DOCUMENT A1 

ERASE PRFILE4 DOCUMENT A1 

You could also use a CMS EXEC to obtain a listing of files on a 
virtual disk. If you want, you can use one of the other LISTFILE command 
options in conjunction with the EXEC option to get more information 
about the files listed. For example, 

listfile * * a (exec date 

produces a CMS EXEC that contains, in addition to the filename, 
filetype, and filemode of each file listed, the file format and size, 
and date information. You can then use the PRINT command to obtain a 
printed copy: 

print cms exec 

Before printing this file, you may want to use the SORT command to 
sort the list into alphabetic order by filename, by filetype, or both, 
for example 

sort cms exec a cmssort exec a 

When you are prompted to enter sort fields, you can enter 

1 26 

The file CMSSORT EXEC that is created contains a completely alphabetical 
list . 
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MODIFYING CMS EXECS 

A CMS EXEC is like any other CMS file; you can edit it, erase it, rename 
it, or change it. If you have created it to catalog a particular group 
of files, you might want to rename it; each time you use the LISTFILE 
command with the EXEC option a CMS EXEC is created, and any old CMS EXEC 
is erased. To rename it, you can use the CMS RENAME command, or, if you 
are editing it, you can rename it when you file it: 

edit cms exec 
input Scontrol off 
file prfile exec 

You might also want to edit a CMS EXEC to provide it with more 
numeric variables, for example: 

edit cms exec 

input Scontrol off 

input cp spool printer class s cont 

change /a1/a1 S3 S4 85 66/ * 



input cp spool printer nocont 
input cp close printer 
file prfile exec 
prfile print % (cc 

When this EXEC is executed, the variable &1 is substituted with PRINT, 
the variable &2 is set to a null string (the special character % 
indicates that you are not passing an argument to it) , and &3 and SU are 
set to the PRINT command option (CC , so that the files in the EXEC print 
with carriage control. The CP commands that are inserted ensure that 
the files print as a single spool file, and not individually. 



Summary of the EXEC Language Facilities 

The EXEC processor, or interpreter, recognizes keywords that begin with 
the special character ampersand (&) . Keywords may indicate: 

• Control statements 

• Built-in functions 

• Special variables 

• Arguments 

You may also define your own variables in an EXEC file; the EXEC 
interpreter can process them as long as they begin with an ampersand. 
The following pages briefly discuss the kinds of things you can do with 
an EXEC, introduce you to the control statements, built-in functions, 
and special variables, and give some examples of how to use the EXEC 
processor. If you want more information on writing EXEC procedures, see 
"Part 3. Learning To Use EXEC." For specific information on the format 
and usage rules for any EXEC statement or variable, consult the VMZ3_Z.Q : 
CMS Command and Macro Reference. 

In general the following rules apply to entering lines into an EXEC 
procedure: 

1. Most input lines (with a few exceptions) are scanned during 
execution of the EXEC. Every word on a line is padded or truncated 
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to fit into an 8-character "token." So, for example, if you enter 
the EXEC control statement 

Stype today is Wednesday 

when this EXEC is executed, the line is displayed at your terminal: 

TODAY IS WEDNESDA 

The lines that are not tokenized are those that begin with an * 
(and are considered comments), and those that follow an &BEGEMSG, 
&BEGPUNCH, &BEGSTACK, or 6BEGTYPE control statement, up to an SEND 
statement. 

2. You can enter input lines beginning in any column. The only time 
that you must enter an EXEC line beginning in column 1 is when you 
are using the SEND control statement to terminate a series of lines 
being punched, stacked, or typed. 



ARGUMENTS AND VARIABLES 

Most EXEC processing is contingent on the value of variable 
expressions. A variable expression in an EXEC is a symbol that begins 
with an ampersand (&) . When the EXEC interpreter processes a line and 
encounters a variable symbol, it substitutes the variable with a 
predefined value, if the symbol has been defined. symbols can be 
defined in three ways: (1) when passed as arguments to the EXEC, (2) by 
assignment statements, (3) interactively, as a result of a SREAD ARGS or 
6READ VARS control statement. 

You can pass arguments to EXEC files when you invoke them. Each 
argument you enter is assigned a variable name: the first argument is 
61, the second is &2, the third is S3, and so on. You can assign values 
for up to 30 variables this way. For example, if an EXEC is invoked: 

scan alpha 2 notype print 

the variable &1 has a value of ALPHA, the variable 62 has a value of 2, 
S3 is NOTYPE and 64 is PRINT. ; These values remain in effect until you 
change them. 

You can test the arguments passed in several ways. The special 
variable &INDEX contains the number of arguments received. Using the 
example SCAN ALPHA 2 NOTYPE PRINT, the statement 

&IP &INDEX EQ 4 &GOTO -SET 

would be true, since four arguments were entered, so a branch to the 
label -SET is taken. 

You can change the values of arguments or assign values using the 
&ARGS control statement. For example, 

6IF SINDEX EQ &ARGS ABC 

assigns the values A, B, and C to the variables 61, 62, and 63 when the 
EXEC is invoked without any arguments. 

Use the &READ ARGS control statement to enter arguments 
interactively. For example, if your EXEC file contains the line 

&READ ARGS 
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when this line is executed, the EXEC issues a read to your virtual 
machine so that you can enter up to 30 arguments, to be assigned to the 
variables S1 , S2 , and so on. 



ASSIGNMENT STATEMENTS 

User-defined variable names begin with an ampersand (&) and contain up 
to seven additional characters. These variables can contain numeric or 
alphameric data. You define and initialize EXEC variables in assignment 
statements. In an assignment statement, the value of the expression on 
the right side of the egual sign is assigned to the variable named on 
the left of the egual sign. For example, 

8A = 35 

is an assignment statement that assigns the numeric value 35 to the 
variable symbol SA. A subseguent assignment statement might be: 

&B = &A + 10 

After this assignment statement executes, the value of SB would be 35 
plus 10, or 45. 

You can use the &READ control statement to assign variable names 
interactively. For example, when the statement 

&READ VABS &NAME &AGE 

is executed, the EXEC issues a read to your virtual machine, and you can 
enter a line of data. The first two words, or tokens, you enter are 
assigned to the variable symbols 6NAME and SAGE, respectively. 



J?J3ii Xaii^bles 

If you use a variable name that has not been defined the variable symbol 
is set to a null string by the EXEC processor when the statement is 
executed. For example, if you have entered only two arguments on the 
EXEC command line, then the statement 

SIF S3 EQ CONT SERROR SCONTINUE 

is interpreted 

&IF EQ CONT SERROR SCONTINUE 

SERROR and SCONTINUE are recognized by EXEC as control statements. 
Since S3 is undefined, however, it is replaced by blanks and the 
resulting line produces an error during EXEC processing. You can 
prevent the error, and allow for null arguments or variables, by 
concatenating some other character with the variable. A period is used 
most freguently: 

SIF .S3 EQ .CONT SERROR SCONTINUE 
If S3 is undefined when this line is scanned, the result is 

SIF . EQ .CONT SERROR SCONTINUE 
which is a valid control statement line. 

110 IBM VM/370: CMS User's Guide 



BUILT-IN FUNCTIONS AND SPECIAL VARIABLES 



The EXEC built-in functions are similar to those of higher-level 

languages. Y6u can use the EXEC built-in functions to define variable 
symbols in an EXEC procedure. 

Figure 8 summarizes the built-in functions. It shows, given the 

variable SA, the values resulting in a variable SB when a built-in 

function is used to assign its value. Notice that all of the built-in 

functions are used on the right-hand side of assignment statements. Only 

the 8LITERAL built-in function can be used in control statements, for 
example: 

STYPE SLITERAL SA 



Function | Usage 



I Exam] 


pie 


1 SB | 


| SA = 


123 




I SB = 


SCONCAT SA 55 


12355| 


| SB = 


SDATATYPE SA 


NUN | 


| SB = 


SLENGTH SA 


3 I 


| SB = 


SLITERAL SA 


SA | 


| SB = 


SSUBSTR SA 2 2 


23 | 



SCONCAT 

SDATATYPE 

SLENGTH 

SLITERAL 

SSUBSTR 



Concatenates tokens into a 

single token. 
Assigns the data type (NUM 

or CHAR) to the variable. 
Assigns the length of a 

token to a variable. 
Prohibits substitution of a 

variable symbol. 
Extracts a character string 

from a token. 






Figure 8. Summary of EXEC Built-in Functions 



FLOW CONTROL IN AN EXEC 



An EXEC is processed line by line: if a statement is encountered that 
passes control to another line in the procedure, execution continues 
there and each line is, again, executed seguentially . You can pass 
control with an SGOTO control statement: 

SGOTO -BEGIN 

where BEGIN is a label. All labels in EXEC files must begin with a 
hyphen, and must be the first token on a line. For example, 

-LOOP 

A label may have control statements or commands following it, for 
example 

-HERE SCONTINUE 

which indicates that the processing is to continue with the next line, 
or 

-END SEXIT 

The SEXIT control statement indicates that the EXEC processor should 
terminate execution of the EXEC and return control to CMS. You can also 
specify a return code on the SEXIT control statement: 
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SEXIT 6 

results in a "(00006)" following the "R" in the CMS Ready message. If 
you invoke a CMS command froa the EXEC, you can specify that the return 
code from the CMS command be used: 

SEXIT SRETCODE 

Since the SRETCODE special variable is set after each CMS command that 
is executed, you can test it after any command to decide whether you 
want execution to end. For example, you could use the SIF control 
statement to test it: 

6IF SRETCODE NE SEXIT SRETCODE 

"SEXIT SRETCODE" places the value of the CMS return code in the CMS 
Ready message. You could place a line similar to the above following 
each of your CMS command lines, or you could use the &ERR0R control 
statement, that will cause an exit as soon as an error is encountered: 

SERROR SEXIT SRETCODE 

or you could use the SERROR control statement to transfer control to 
some other part of your EXEC: 

SERROR SGOTO -CHECK 



-CHECK 



Another way to transfer control to another line is to use the SSKIP 
control statement: 

SSKIP 10 

transfers control to a line that is 10 lines below the SSKIP line. You 
can transfer control above the current line as well: 

SIF SX NE SY SSKIP -3 

Transferring control with SSKIP is faster, when an EXEC is executing, 
than it is with SGOTO, but modifying your EXEC files becomes more 
difficult, particularly when you add or delete many lines. 

You can use combinations of SIF, SGOTO, and SSKIP to set up loops in 
an EXEC. For example: 

SX = 1 

SIF SX = 4 SGOTO -EHDPRT 

PRINT FILE&X TEST A 

SX = SX + 1 

SSKIP -3 

-ENDPRT 

Or, you can use the SLOOP control statement: 

SX = 1 

SLOOP 2 SX > 3 

PRINT FILESX TEST 

SX = SX ♦ 1 

-ENDPRT 
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In both of these examples, a loop is established to print the files 
FILE1 TEST, FILE2 TEST, and FiLE3 TEST. &X is initialized with a value 
of 1 and then incremented within the loop. The loop executes until the 
value of SX is greater than 3.; As soon as this condition is met, control 
is passed to the label -ENDPRT. 



COMPARING VARIABLE SYMBOLS AND CONSTANTS 

In an EXEC, you can test whether a certain condition is true, and then 
perform some function based on the decision. Some examples have already 
appeared in this section, such as 

SLOOP 3 SX EQ &Y 

In this example, the value of the variable SX is tested for an equal 
comparison with the value of the variable &Y. The loop is executed until 
the condition (SX equal to &Y) is true. 

The logical comparisons you can make are: 



Condition 


Mnemonic 


Symbol 


equal 


EQ 


= 


not equal 


NE 


-i= 


greater than 


GT 


> 


less than 


LT 


< 


greater than 






or equal to 


GE 


> = 


less than or 






equal to 


LE 


< = 



When you are testing a condition in an EXEC file, you can use either the 
mnemonic or the symbol to represent the condition: 

SIF SA LT SB SGOTO -NEXT 

is the same as 

SIF SA < SB SGOTO -NEXT 



DOING I/O WITH AN EXEC 

You can communicate with your terminal using the STYPE and &READ control 
statements. Use STYPE to display a line at your terminal: 

STYPE ASMBLNG &1 ASSEMBLE 

When this line is processed, if the variable &1 has a value of PR0G1, 
the line is displayed as 

ASMBLNG PR0G1 ASSEMBLE 

Use the SREAD control statement when you want to be able to enter 
data, variables, or control statements into your EXEC file while it is 
executing. If you use it in conjunction with an STYPE statement, for 
example 

STYPE DO YOU WANT TO CONTINUE ? 
SREAD SANS 
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you could test the variable &ANS in your EXEC to find out how processing 
is to continue. 

The &BEGTYPE control statement can be followed by a sequence of lines 
you want to be displayed at the terminal. For example, if you want to 
display 10 lines of data, instead of using 10 8TYPE control statements, 
you could use 

SBEGTYPE 

linel 

line2 



line 10 
SEND 

The SEND control statement indicates the end of the lines to be typed. 

You can also use the &BEGTYPE control statement when you want to type a 

line that contains a word with more than 8 characters in it, for 
example: 

SBEGTYPE 

TODAY IS WEDNESDAY 

SEND 

The EXEC interpreter, however, does not perform substitutions on lines 
entered this way. The lines 

&A = DOG 

SBEGTYPE 

MY &A IS NAMED FIDDLEFADDLE 

SEND 

result in the display 

MY SA IS NAMED FIDDLEFADDLE 

You must use the &TYPE statement when you want to display variable data; 
you must use the SBEGTYPE control statement to display words with more 
than 8 characters. 

To type null or blank lines at your terminal (to make output 
readable, for example), you can use the SSPACE control statement: 

SSPACE 5 



^§LiM Your Virtual Card Punch 



You can punch lines of tokens into your virtual card punch with the 
SPUNCH control statement : 

&P0NCH &NAME &TOTAL 

When you want to punch more than one line of data, or a line that 
contains a word of more than 8 characters in it, you should use the 
SBEGPUNCH control statement preceding the lines you want to punch, and 
follow them with an SEND statement. The EXEC processor does not 
interpret these lines, however, so any variable symbols you enter on 
these lines are not substituted. 
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When you punch lines from an EXEC procedure what you are actually 
doing is creating a file in your virtual card punch. To release the 
file for processing, you must close the punch: 

cp close punch 

The destination of the file depends on how you have spooled your punch. 
If you have spooled it to yourself, the file is placed in your virtual 
card reader, and you can read it onto a virtual disk using the READCARD 
command. 



St ackina Lines 

The EXEC control statements SSTACK and 8BEGSTACK allow you to stack 
lines in your terminal console, to be executed as soon as a read occurs 
in your virtual machine. Stacking is useful when you use commands that 
require responses, for example, the SORT command: 

&STACK 1 20 

SORT INFILE FILE A OUTFILE FILE A 

When the SORT command is executed, a prompting message is issued, the 
virtual machine read occurs, and the response that you have stacked is 
read. If you do not stack a response to this command, your EXEC does 
not continue processing until you enter the response from your 
terminal. 

Stacking is useful in creating edit macros, or when you are editing 
files from EXEC procedures. 



MONITORING EXEC PROCEDURES 

Two EXEC control statements, 8C0NTR0L and STIME, control how much 
information is displayed at your terminal while your EXEC file is 
executing. This display is called an execution summary. 

Since, usually, you do not receive a CMS Ready message after the 
execution of each CMS command in an EXEC, you do not receive the timing 
information that is provided with the Ready message. If you want this 
timing information to appear, you can specify 

STIME ON 

or you can type the CPU times at particular places by using: 

STIME TYPE 

The &CONTROL control statement allows you to specify whether certain 
lines or types of information are displayed during execution. By 
default, CP and CMS commands are displayed before they are executed. If 
you do not wish to see them displayed, you can specify 

SCONTROL OFF 

You might find it useful, when you are debugging your EXECs, to use 

SCONTROL ALL 
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ihen you use this form, all EXEC statements, as well as all CP and CMS 
commands, are displayed and you can see the variable substitutions being 
performed and the branches being taken in a procedure. 



Summary of EXEC Control Statements and Special Variables 

Figures 9 and 10 summarize EXEC control statements and special 
variables. 





Control 


Statement 

ion/ 
:xxx ) 


I Function | 


Svariable 


= {strir 
) ae 

\ funct 
(x« XX J 


I Assigns a value to the symbol | 
(specified by Svariable; the | 
| equal sign must be preceded | 
land followed by a blank. j 


8AEGS [arg 


f1 [arg2 


...[arg30]]] 


| Redefines the variable symbols | 
|S1, 82... with the values of | 
I'argV, ' arg2', . .., and re- | 
| sets the variable SINDEX. j 


SBEGEMSG [ALL] 
linel 
line2 




| Displays the following lines | 
I as CMS error messages, without! 
Iscanning them. | 


SEND 








SBEGPUNCH 
linel 
line2 


[ ALL] 




I Punches the following lines | 
| in the virtual card punch, | 
| without scanning them. | 


SEND 








SBEGSTACK 
linel 
line2 

• 


r t 

| FIFO | 
|LIF0| 

L J 


r t 
|ALL| 

L J 


IStacks the following lines | 
| in the console input buffer, | 
| without scanning them. | 


SEND 








SBEGTYPE [ 
line 1 
line2 


ALL] 




IDisplays the following lines | 
I at the console, without | 
Iscanning them. | 


SEND 








SCONTIN0E 






Provides a branch address for | 

l&ERROR, &GOTO, and other con- | 

ditional branching statements.! 



Figure 9. Summary of EXEC Control Statements (Part 1 of 3) 
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Control Statement 



Function 



6C0NTR0L 



r ir i r t r -\ 

|OFF | |MSG | |TIHE | |PACK | 

| ERROR | |NOMSG| |NOTIME| |NOPACK| 

| CMS | •- J »• " J L J 

| ALL | 
i j 



6EMSG mmmnnns [ tok 1 [...tokn]] 



SEND 



r i 

&ERROR | executable-statement | 
|S CONTINUE | 

L "" J 



r i 

&EXIT | return-code | 

I | 

L J 

&GOTO ( TOP 

/ linenumber 
I -label 



Sets, until further notice, 
the characteristics of the 
execution summary of the EXEC, 
which is displayed at the 
console. 



Displays a line of tokens 
as a CMS error message. 



Terminates a series of lines 
following an SBEGEMSG, 
&BEGPUNCH, &BEGSTACK, or 
6BEGTYPE control statement. 

Executes the specified 
statement whenever a CMS 
command returns a nonzero 
return code. 



Exits from the EXEC file with 
the given return code. 



Transfers control to the top 
of the EXEC file, to the given 
line, or to the line starting 
with the given label. 



HEX /ON ) 



Turns on or off hexadecimal 
conversion. 




EQ 

NE 

LT 

>LE 

gt| 
'ge 



< 

<= 
> 
>= 



( tok2 ) executable- 
< &$ > statement 



Executes the specified 
statement if the condition is 
satisfied. 



&LOOP 



{ -label /{ 



condition 



Loops through the following n 
lines, or down to (and includ- 
ing) the line at label, for 
m times, or until the 
condition is satisfied. 



&PUNCH [tok! [...tokn]] 



i 



Punches the specified tokens 
to your virtual card punch. 



Figure 9. Summary of EXEC Control Statements (Eart 2 of 3) 
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Figure 9. Summary of EXEC Control Statements (Part 3 of 3) 
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Osage 




&$ 



&DISKX 



&DISK* 



&DISK? 



6 DOS 



&EXEC 



& GLOBAL 



SGLOBALn 



&INDEX 

&LINENUM 
&READFLAG 

&RETCODE 

STYPEFLAG 

&0 



Arguments passed to an EXEC are assigned to 
the variables SI through &30. 

Test whether all (&*) or any (&$) of the 
arguments passed to EXEC have a particular 
value. 

Indicates whether the disk access at mode *x* 
is a CMS OS, or DOS disk, or not accessed 
(CMS, OS, DOS, or NA) . 

Contains the mode letter of the first read/write 
disk in the CMS search order, or NONE if no 
read/write disk is accessed. 

Contains the mode letter of the read /write disk 
with the most available space or NONE, if no 
read/write disk is accessed. 

Indicates whether or not the CMS/DOS environment 
is active (ON or OFF) . 

Contains the filename of the EXEC file currently 
being executed. 

Has a value ranging from 1 to 19, to indicate 
the recursion (nesting) level of the EXEC that 
is currently executing. 

The variables &GL0BAL1 through &GL0BAL9 can 
contain integral numeric values, and can be 
passed among different recursion levels. If 
not explicitly set, the variable will have a 
value of 1. 

Contains the number of arguments passed to 
the EXEC on the command line or the number of 
arguments entered as a result of an &ARGS or 
&BEAD ARGS control statement. 

Contains the current line number in the EXEC. 

Indicates whether (STACK) or not (CONSOLE) 
there are lines stacked in the terminal input 
buffer (console stack) . 

Contains the return code from the most recently 
executed CMS command. 

Indicates whether (RT) or not (HT) output is 
being displayed at the console. 

Contains the name of the EXEC file. 



Set By 



User 



EXEC 



User 



User 



User 



User 



EXEC 



EXEC 



User 



EXEC 

EXEC 
EXEC 

CMS 

EXEC 

User 



Ml' 

User: Variables are assigned values by EXEC but you may modify them. 

EXEC: You may not modify these variables. 

CMS: You may assign a value to this variable but it is reset at the 
completion of each CMS command. 

Figure 10. EXEC Special Variables 
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CMS Unit Record Device Support 

CMS supports one virtual card reader at address 00C, one virtual card 
punch at address 00D, and one virtual printer at address 00E. When you 
invoke a CMS command or execute a program that uses one of these unit 
record devices, the device must be attached at the virtual address 
indicated. 



USING THE CP SPOOLING SYSTEM 

Any output that you direct to your virtual card printer or punch, or any 
output you receive through your card reader, is controlled by the 
spooling facilities of the control program (CP) . Each output unit is 
known to CP as a spool file, and is queued for processing with the spool 
files of other users on the VM/370 system. Ultimately, a spooled 
printer file or a spooled punch file may be released to a real printer 
or card punch for printing or punching. 

The final disposition of a unit record spool file depends on the 
spooling characteristics of your virtual unit record devices, which you 
can alter with the CP command SPOOL. To find out the current 
characteristics of your unit record devices you can issue the command: 

cp query ur 

You might see, as a response to this, the display: 

RDR 00C CL A NOCONT NOHOLD EOF READY 

PUN 00D CL A NOCONT NOHOLD COPY 01 READY 

00D FOR CMSGDE DIST 13SCRIPT 

PRT 00E CL A CONT HOLD COPY 01 READY 

00E FOR CMSGDE DIST 13SCRIPT 

Some of these characteristics, and the ways you can modify them, are 
discussed below. When you use the SPOOL command to control a virtual 
unit record device, you do not change the status of spool files that 
already exist, but rather set the characteristics for subsequent 
output. For information on modifying existing spool files, see 
"Altering Spool Files," below. 

CLASS (CL) : Spool files, in the CP spool file queue, are grouped 
according to class, and all files of a particular class may be processed 
together, or directed to the same real output device. The default 
values for your virtual machine are set in your VM/370 directory entry, 
and are probably the standard classes for your installation. 

You may need, however, to change the class of a device if you want a 
particular type of output, or some special handling for a spool file. 
For example, if you are printing an output file that requires special 
forms, and your installation expects that output to be spooled class Y, 
issue the command: 

cp spool printer class y 
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All subsequent printed output directed to your printer at virtual 
address 00E (all CMS output) is processed as class Y. 

HOLD: If you place a HOLD on your printer or punch r any files that you 
print or punch are not released to the control program^ spooling gueue 
until you specifically alter the hold status. By placing your output 
spool files in a hold status, you can select which files you print or 
punch, and you can purge duplicate or unwanted files. To place printer 
and punch output files in a hold status issue the commands: 

cp spool printer hold 
cp spool punch hold 

Note: When you issue a SPOOL command for a unit record device, you can 
refer to it by its virtual address, as well as by its generic device 
type (for example, CP SPOOL E HOLD). 

When you have placed a hold status on printer or punch files and you 
produce an output file for one of these devices, CP sends you a message 
to remind you that you have placed the file in a hold: 

PRT FILE xxxx FOR userid COPY xx HOLD 
If, however, you have issued the command 

cp set msg off 

then you do not receive the message. 

When you place a reader file in a hold status, then the file remains 
in the card reader until you remove the hold status and read it, or you 
purge it. 

COPY: If you want multiple copies of a spool file, you should use the 
COPY operand of the SPOOL command: 

cp spool printer copy 10 

If you enter this command, then all subsequent printer files that you 
produce are each printed 10 times, until you change the COPY attribute 
of your printer. 

FOR: You can spool printed or punched output under another userid 1 s name 
by using the FOR operand of the SPOOL command. For example, if you enter 

cp spool printer for Charlie 

Then, all subsequent printer files that you produce have, on the output 
separator page, the userid CHARLIE and the distribution code for that 
user. The spool file is then under the control of that user, and you 
cannot alter it further. 

QONT, NOCONT: You can print or punch many spool files, but have them 

print or punch as one continuous spool file if you use the CONT operand 

on the SPOOL command. For example, if you issue the following sequence 
of commands: 

cp spool punch cont to brown 

punch asml assemble 

punch asm2 assemble 

punch asm3 assemble 

cp spool punch nocont 

cp close punch 
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Then, the three files ASM1 ASSEMBLE, ASM2 ASSEMBLE, and ASM3 ASSEMELE, 
are punched to user BROWN as a single spool file. When user BROWN reads 
this file onto a disk, however, CMS creates separate disk files. 

TO: When you spool your printer or punch to another userid, all output 
from that device is transferred to the virtual card reader of the userid 
you specify. When you are punching a CMS disk file, as in the example 
above, you should use the TO operand of the SPOOL command to specify the 
destination of the punch file. 

You can also use this operand to place output in your own virtual 
card reader by using the * operand: 

cp spool printer to * 

After you enter this command, subseguent printed output is placed in 
your virtual card reader. You might use this technigue as an alternative 
way of preventing a printer file from printing, or, if you choose to 
read the file onto disk from your reader, of creating a disk file from 
printer output. 

Similarly, if you are creating punched output in a program and you 
want to examine the output during testing, you could enter: 

cp spool punch to * 

so that you do not punch any real cards or transfer a virtual punch file 
to another user. 



ALTERING SPOOL FILES 

After you have reguested that VM/370 print or punch a file, or after you 
have received a file in your virtual card reader and before the file is 
actually printed, punched, or read, you can alter some of its 
characteristics, change its destination, or delete it altogether. 

Every spool file in the VM/370 system has a unigue 4-digit number 
from to 9900 assigned to it, called a spoolid. You can use the spoolid 
of a file to identify it when you want to do something to it. You can 
also change a group of files, by specifying that all files of a 
particular class be altered in some way, or you can manipulate all of 
your spool files for a certain device at the same time. 

The CP commands that allow you to manipulate spool files are CHANGE, 
ORDER, PURGE, and TRANSFER. In addition, you can use the CP QUERY 
command to list the status and characteristics of spool files associated 
with your userid. 

When you use any of these commands to reference spool files of a 
particular device, you have the choice of referring to the files by 
class or by spoolid. You can also specify ALL. For example, if you 
enter the command 

cp guery printer all 

you might see the display: 

ORIGINID FILE CLASS RECDS CPY HOLD DATE TIME NAME TYPE DIST 
SCARLET 0211 D PRT 000140 01 USER 07/09 10:25:23 TARA FILE BIN015 
SCARLET 0245 A PRT 000026 01 NONE 07/09 10:25:41 CMSLIB MACLIB BIN015 
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Until any of these files are processed, or in the case of files in the 
hold status, until they are released, you can change the spool file name 
and spool file type (this information appears on the first page or first 
card of output) , the distribution code, the number of copies, the class, 
or the hold status, using the CP CHANGE command. For example, 

cp change printer all nohold 

changes all printer files that are in a hold status to a nohold status. 
The CP CHANGE command can also change the spooling class, distribution 
code, and so on. 

If you decide that you do not want to print a particular printer 
file, you can delete it with the CP PURGE command: 

cp purge printer 7615 

After you have punched a file to some other user, you cannot change 
its characteristics or delete it unless you restore it to your own 
virtual reader. You can do this with the TRANSFER command: 

cp transfer all from usera 

This command returns to your virtual card reader all punch files that 
you spooled to USERA 1 s virtual card reader. 

You can determine, for your reader or printer files, in what order 
they should be read or printed. If you issue the command: 

cp order printer 8195 6547 

Then, the file with spoolid of 8195 is printed before the file with a 
spoolid of 6547. 

The CP spooling system is very flexible, and can be a useful tool, if 
you understand and use it properly. The VMZ170: CP Command Reference for 
General Users contains complete format and operand descriptions for the 
CP commands you can use to modify spool files. 



USING YOUR CARD PUNCH AND CARD READER IN CMS 

The CMS READCARD command reads cards from your virtual card reader at 
address 00C. Cards can be placed in the reader in one of two ways: 

o By reading real punched cards into the system card reader. A CP ID 
card tells the CP spooling system which virtual card reader is to 
receive the card images. 

» By transferring a file from another virtual machine. Cards are 
transferred as a result of a virtual punch or printer being spooled 
with the TO operand, or as a result of the TRANSFER command. Virtual 
card images are created with the CMS PUNCH command, or from user 
programs or EXEC procedures. 

Using l§al Cards 

3Cf you have a deck of punched cards that you want read into your virtual 
Machine card reader, you should punch, preceding the deck, a CP ID card: 

ID HAPPY 
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If you plan to use the READCARD command to read this file onto a CMS 
disk, you can also punch a READ control card that specifies the filename 
and filetype you want to have assigned to the file: 

:READ PR0G6 ASSEMBLE 
Then, to read this file onto your CMS A-disk, you can enter the command 

readcard * 

If a file named PR0G6 ASSEMBLE already exists, it is replaced. 

If you do not punch a READ control card, you can specify a filename 
and filetype on the READCARD command: 

readcard prog6 assemble 

If this spool file contained a READ control card, the card is not read, 
but remains in the file; if you edit the file, you can use the DELETE 
subcommand to delete it. 

If a file does not have a READ control card, and if you do not 
specify a filename and filetype when you read the file, CMS names the 
file READCARD CMSUT1. 

If you are reading many files into the real system card reader, and 
you want to read them in as separate spool files (or you want to spool 
them to different userids) , you must separate the cards and read the 
decks onto disk individually. The CP system, after reading an ID card, 
continues reading until it reaches a physical end of file. 

Using. Your Virtual Card Punch 

When you use the CMS PUNCH command to punch a spool file, a READ control 
card is punched to precede the deck, so that it can be read with the 
READCARD command. If you do not wish to punch a READ control card (also 
referred to as a header card) , you can use the NOHEADER option on the 
PUNCH command: 

punch prog8 assemble * ( noheader 

You should use the NOHEADER option whenever you punch a file that is not 
going to be read by the READCARD command. 

The PUNCH command can only punch records of up to 80 characters in 
length. If you need to punch or to transfer to another user a file that 
has records greater than 80 characters in length, you can use the DISK 
DUMP command: 

disk dump prog9 data 

If your virtual card punch has been spooled to another user, that user 
can read this file using the DISK LOAD command: 

disk load 

Unlike the READCARD command, DISK LOAD does not allow you to specify a 
file identification for a file you are reading; the filename and 
filetype are always the same as those specified by the DISK DUMP command 
that created the spool file. 

A card file created by the DISK DUMP command can only be read onto 
disk by the DISK LOAD command. 
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IlsijQS the MOVEFILE Command 

You can use the MOVEFILE command, in conjunction with the FILEDEF 
command, to place a file in your virtual card reader, or to copy a file 
from your card reader to another device. For example, 

cp spool punch to * 

filedef punch punch 

filedef input disk coffee exec a1 

movefile input punch 

the file COFFEE EXEC A1 is punched to your virtual card punch, (in 
card-image format) and spooled to your own virtual reader. 



Creating Files Using Your Reader and Punch 

Apart from the procedures shown above, that transfer whole files with 
one or two commands, there are other methods you can use to create files 
using your virtual card punch. From a program or an EXEC file, you can 
punch one line at a time to your virtual punch. Then use CLOSE command 
to close the spool file: 

cp close punch 

Depending on how the punch was spooled (the TO setting) , the virtual 
punch file is either punched or transferred to a virtual card reader. 

PUNCHING CARDS USING I/O MACROS: If you write an OS, DOS, or CMS program 
that produces punched card output, you should make an appropriate file 
definition. If you are an OS user, you should use the FILEDEF command 
to define the punch as an output data device; if you are a DOS user, you 
must use the ASSGN command. If you are using the CMS PUNCHC macro, the 
punch is assigned for you. The spooling characteristics of your virtual 
punch control the destination of the punched output. 

PUNCHING CARDS FROM AN EXEC: The EXEC facilities provide two control 
statements for punching cards: SPUNCH, which punches a single line to 
the virtual card punch, and &BEGPUNCH, which precedes a number of lines 
to be punched. You can also, in an EXEC, use the commands PUNCH and 
DISK DUMP to punch CMS files. 



Handling Tape Files in CMS 

There are a variety of tape functions that you can perform in CMS, and a 
number of commands that you can use to control tape operations or to 
read or write tape files. One of the advantages of placing files on 
tapes is portability: it is a convenient method of transferring data 
from one real computing system to another. In CMS, you can use tapes 
created under other operating systems. There are also two CMS commands, 
TAPE and DDR, that create tape files in formats unigue to CMS, that you 
can use to back up minidisks or to archive or transfer CMS files. 

Under VM/370, virtual addresses 181 through 184 are usually reserved 
for tape devices. In most cases, you can refer to these tapes in CMS by 
using the symbolic names TAP1 through TAP4. In any event, before you 
can use a tape, you must have it mounted and attached to your virtual 
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machine by the system operator. When the tape is attached, you receive 
a message. For example, if the operator attaches a tape to your virtual 
machine at virtual address 181, you receive the message 

TAPE 181 ATTACHED 

The various types of tape files, and the commands and programs you 
can use to read or write them are: 

IhRM Command: The CMS TAPE command creates tape files from CMS disk 
files. They are in a special format, and should only be read by the CMS 
TAPE LOAD command. For examples of TAPE command operands and options, 
see "Using the CMS TAPE Command." 

TAPPDS Command: The TAPPDS command creates CMS disk files from OS or DOS 
seguential tape files, or from OS partitioned data sets. 

IMJMC Command: The TAPEMAC command creates CMS MACLIB files from OS 
macro libraries that were unloaded onto tape with the IEHMOVE utility 
program. 

MOVEFILE Command: The MOVEFILE command can copy a seguential tape file 
onto disk, or a disk file onto tape. Or, it can move files from your 
card reader to tape, or from tape to your card punch. 

User Programs: You can write programs that read or write sequential tape 
files using OS, DOS, or CMS macros. 

Access Method Services: Tapes created by the EXPORT function of Access 
Method Services can be read only using the Access Method Services IMPORT 
function. Both the IMPORT and EXPORT functions can be accomplished in 
CMS using the AMSERV command. The Access Method services REPRO function 
can also be used to copy sequential tape files. 

£51 l£23L£§I : Tne DDR program, invoked with the CMS command DDR, dumps 
the contents of a virtual disk onto tape, and should be used to restore 
such files to disk. 



USING THE CMS TAPE COMMAND 

The CMS TAPE command provides a variety of tape handling functions. It 
allows you to selectively dump or load CMS files to and from tapes, as 
well as to position, rewind, and scan the contents of tapes. You can 
use the TAPE command to save the contents of CMS disk files, or to 
transfer them from one VM/370 system to another. The following example 
shows how to create a CMS tape with three tape files on it, each 
containing one or more CMS files, and then shows how you, or another 
user, might use the tape at a later time. 

The example is in the form of a terminal session and shows, in the 
••Terminal Display" column, the commands and responses you might see. 
System messages and responses are in uppercase, and user-entered 
commands are in lowercase. The "Comments" column provides explanations 
of the commands and responses. 
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Terminal Display 
TAPE T5T ATTACHED 

listfile * assemble a (exec 

R; 

cms tape dump 

TAPE DUMP PR0G1 ASSEMBLE A1 

DUMPING 

PR0G1 ASSEMBLE A1 

TAPE DUMP PB0G2 ASSEMBLE A1 

DUMPING 

PR0G2 ASSEMBLE A1 

TAPE DUMP PR0G3 ASSEMBLE A1 



Comments 

Message indicates that the tape is 
attached. 

Prepare to dump all ASSEMBLE files 
by using the LISTFILE command EXEC 
option; then execute the CMS EXEC 
using TAPE and DUMP as arguments. 

The TAPE command responds to each 
TAPE DUMP by printing the file 
identification of the file being 
dumped. 



TAPE DUMP PR0G9 ASSEMBLE A1 

DUMPING 

PR0G9 ASSEMBLE A1 

R; 

tape wtm 

R; 

tape dump mylib maclib a 

DUMPING 

MYLIB MACLIB A1 

R; 

tape dump cmslib maclib * 

DUMPING 

CMSLIB MACLIB S2 

R; 

tape wtm 

R; 

tape dump mylib txtlib a 

DUMPING 

MYLIB TXTLIB A1 

R; 

tape wtm 2 

R; 

tape rew 

R; 

tape scan (eof 4 
SCANNING.... 
PR0G1 ASSEMBLE A1 
PR0G2 ASSEMBLE A1 
PR0G3 ASSEMBLE A1 
PR0G4 ASSEMBLE A1 
PR0G5 ASSEMBLE A1 
PR0G6 ASSEMBLE A1 
PR0G7 ASSEMBLE A1 
PR0G8 ASSEMBLE A1 
PR0G9 ASSEMBLE A1 
END-CF-FILE OR END-OF-TAPE 
MYLIB MACLIB A1 
CMSLIB MACLIB S2 
END-OF-FILE OR END-OF-TAPE 
iMYLIB TXTLIB A1 
END-OF-FILE OR END-OF-TAPE 
END-OF-FILE OR END-OF-TAPE 

R; 

*cp det 181 

TAPE 181 DETACHED 



The last file, PROG9 ASSEMBLE, is 
dumped. 



The TAPE command writes a tape mark 
to indicate an end-of-file. 

Two macro libraries are dumped, 

by specifying the file identifiers, 



Another tape mark is written. 
A TEXT library is dumped. 



Two tape marks are written to 

indicate the end of the tape. 
The tape is rewound. 

The tape is scanned to verify 

that all of the files are on it, 



Tape mark indication. 



Two tape marks indicate the end 
of the tape. 

The CP DETACH command rewinds 
and detaches the tape. 
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Terminal Display c 2 m J5 e S£§ 

* 

* The tape created above is going to be read. 

* 



TAPE 181 ATTACHED 

tape load progU assemble 

LOADING 

PR0G4 ASSEMBLE A1 

R; 

tape scan 

SCANNING.... 

PR0G5 ASSEMBLE A1 

PR0G6 ASSEMBLE A1 

PR0G7 ASSEMBLE A1 

PR0G8 ASSEMBLE A1 

END-OF-FILE OR END-OF-TAPE 

R; 

tape scan 

SCANNING.... 

MYLIB MACLIB A1 

CMSLIB MACLIB S2 

END-OF-FILE OR END-OF-TAPE 

R; 

tape bsf 2 

R; 

tape fsf 

R; 

tape, load (eof 2 

LOADING..... 

MYLIB MACLIB A1 

CMSLIB MACLIB A2 

MYLIB TXTLIB A1 

END-OF-FILE OR END-OF-TAPE 

R; 

#cp detach 181 
TAPE 181 DETACHED 



Message indicating the tape is 
attached. 

One file is to be read onto disk. 

The TAPE command displays the 
name of the file loaded. Any 
existing file with the same 
filename and filetype is erased. 

The remainder of the first tape 
file is scanned. 



Indication of end of first tape file. 
The second tape file is scanned 



The tape is backed up and 

postioned in front of the 

last tape file. 
The tape is forward spaced past 

the tape mark. 
The next two tape files are 

going to be read. 



The tape is detached. 



TAPE LABELS IN CMS 



CMS cannot read tape labels on tapes created under either OS or DOS. 

When you want to read a tape file created using either of these 

operating systems, you have to use the CMS TAPE command to position the 
tape following the tape label: 



tape fsf 

If you do not forward space the tape, you receive an 
indication the first time you attempt to read the tape. 



end-of-file 
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THE MOVEFILE COMMAND 

The MOVEFILE command can copy sequential tape files into disk files, or 
sequential disk files onto tape. It can be particularly useful when you 
need to copy a file from a tape and you do not know the format of the 
tape. 

To use the MOVEFILE command, you must first define the input and 

output files using the FILEDEF command. For example, to copy a file from 

a tape attached to your virtual machine at virtual address 181 to a CMS 
disk, you would enter: 

filedef input tapl 

filedef output disk tape file a 

movefile input output 

This sequence of commands creates a file named TAPE FILE A1. Then use 
CMS commands to manipulate and examine the contents of the file. 



TAPES CREATED Bl OS UTILITY PROGRAMS 

The CMS command TAPPDS can read OS partitioned and sequential data sets 
from tapes created by the IEBPTPCH, IEBOPDTE, and IEHMOVE utility 
programs. When you use the TAPPDS command, the OS data set is copied 
into a CMS disk file, or in the case of partitioned data sets, into 
multiple disk files. 

I.EBPTPCH: Sequential or partitioned data sets created by IEBPTPCH must 
be unblocked for CMS to read them. If you have a tape created by this 
utility, each member (if the data set is partitioned) is preceded with a 
card that contains ,, MEMBER=membername" . If you read this tape with the 
command: 

tappds * 

then, CMS creates a disk file from each member, using the membername for 
the filename and assigning a filetype of CMSUT1. If you want to assign a 
particular filetype, for example TEST, you could enter the command as 
follows: 

tappds * test 

If the file you are reading is a sequential data set, you should use the 
HOPDS option of the TAPPDS command: 

tappds test file (nopds 

The above command reads a sequential data set and assigns it a file 
identifier of TEST FILE. If you do not specify a filename or filetype, 
the default file identifier is TAPPDS CMSUT1. 

IBBUPDTE: Tapes in control file format created by the IEBDPDTE utility 
program can be read by CMS. Data sets may be blocked or unblocked, and 
may be either sequential or partitioned. Since files created by 
IEBUPDTE contain ./ADD control cards to signal the addition of members 
to partitioned data sets, you must use the C0L1 option of the TAPPDS 
command. Also, you must indicate to CMS that the tape was created by 
IEBUPDTE. For example, to read a partitioned data set, you would enter 
the command 

tappds * test (update coll 
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The CMS disk files created are always in unblocked, 80-character 
format. 

IEHMOVE: OS unloaded partitioned data sets on tapes created by the 
IEHMOVE utility program can be read either ty the TAPPDS command or by 
the TAPEMAC command. The TAPPDS command creates an individual CMS file 
from each member of the PDS. 

If the PDS is a macro library* you can use the TAPEMAC command to 
copy it into a CMS MACLIB. A MACLIB, a CMS macro library, has a special 
format, and can usually be created only by using the CHS MACLIB 
command. If you use the TAPPDS command, you have to use the MACLIB 
command to create the macro library from individual files containing 
macro definitions. 



SPECIFYING SPECIAL TAPE HANDLING OPTIONS 

For most of the tape handling that you do in CMS, you do not have to be 
concerned with the density or recording format of the magnetic tapes 
that you use. There are, however, some instances when it may be 
important and there are command options that you can use with the TAPE 
command MODESET operand and with ASSGN and FILEDEF command options. 

The specific situations, and the command options you should use, are 
listed below. 

• If you are reading or writing a 7-track tape, and the density of the 
tape is either 200 or 556 bpi, you must specify DEN 200 or DEN 556. 

• If you are reading or writing a 7-track tape with a density of 800 
bpi, you must specify 7TRACK. 

• If you are reading or writing a 7-track tape without using the data 
convert feature, you must use the TRTCH option. 

• If you are writing a tape using a 9-track dual density tape drive, 
and you want the density to be 800 (on an 800/1600 drive) or 6250 (on 
a 1600/6250 drive), then you must specify DEN 800 or DEN 6250. 



Using the Remote Spooling Communications Subsystem (RSCS) 

If your VM/370 installation is on a Remote Spooling Communications 
Subsystem (RSCS) network, you can send printer, punch, or reader spool 
files to users at remote locations. To send a spool file, you must know 
the userid of the virtual machine at your location that is running RSCS, 
and the location identification (locid) of the remote location. If you 
are sending a spool file to a particular user at the remote location, 
you should also know that userid of the user. 

The CP commands that you can use to transmit files across the network 
are TAG and SPOOL. The TAG command allows you to specify the locid and 
userid that are to receive a spool file, or, in the case of tagging a 
printer or punch, of any spool files produced by that device. With the 
SPOOL command, you spool your virtual device to the RSCS virtual 
machine. You can also use the TRANSFER command to transfer files from 
your own virtual card reader. 

The CP commands TAG, SPOOL, and TRANSFER are discussed in detail in 
the publication VH^370: CP Co.mman.d Reference for General Users. 
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Part 2. Program Development Using CMS 



You can use CMS to write, develop, update, and test: 

• OS programs to execute either in the CMS environment (using OS 
simulation) or in an OS virtual machine. 

• DOS programs to execute in either the CMS/DOS environment or in a DOS 
virtual machine. 

• CMS programs to execute in the CMS environment. 

The OS and DOS simulation capabilities of CMS allow you to develop OS 
and DOS programs interactively in a time-sharing environment. When your 
programs are thoroughly tested, you can execute them in an OS or DOS 
virtual machine under the control of VM/370. 

"Section 8. Developing OS Programs Under CMS" is for programmers who 
use OS. It describes procedures and techniques for using CMS commands 
that simulate OS functions. 

"Section 9. Developing DOS Programs Under CMS" is for programmers who 
use DOS. It describes procedures and techniques for using CMS/DOS 
commands to simulate DOS/VS functions. 

If you use VSAM and Access Method Services, in either a DOS or an OS 
environment, "Section 10. Using Access Method Services and VSAM in CMS 
and CMS/DOS" provides usage information for you. It describes how to 
use CMS to manipulate VSAM disks and data sets. 

You can use the interactive facilities of CP and CMS to test and 
debug programs directly at your terminal. "Section 11. How VM/370 Can 
Help You Debug Your Programs" shows examples of commands and debugging 
techniques. 

The CMS Batch Facility is a CMS feature that allows you to send jobs 

to another machine for execution. How to prepare and send job streams 

to a CMS batch virtual machine is described in "Section 12. Using the 
CMS Batch Facility." 

As you learn to use CMS, you may want to write programs for CMS 
applications. "Section 13. Programming for the CMS Environment" 
contains information for assembler language programmers: linkage 
conventions, programming notes, and macro instructions you can use in 
CMS programs. 
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Section 8. Developing OS Programs Under CMS 



CMS simulates many of the functions of the Operating System (OS) , 
allowing you to compile, execute and debug OS programs interactively. 
For the most part, you do not need to be concerned with the CMS OS 
simulation routines: they are built into the CMS system. Before you can 
compile and execute OS programs in CMS, however, you must be acguainted 
with the following: 

• OS macros that CMS can simulate 

• Using OS data sets in CMS 

• How to use the FILEDEF command 

• Creating CMS files from OS data sets 

• Using CMS and OS Macro Libraries 

• Assembling Programs in CMS 

• Executing programs 

These topics are discussed below. Additional information for OS VSAM 
users is in "Section 10. Using Access Method Services and VSAM Under CMS 
and CMS/DOS." 

For a practice terminal session using the commands and technigues 
presented in Section 8, see "Appendix D: Sample Terminal Sessions." 



4 Note About Terminology 

The CMS system uses many OS terms, but there are a number of OS 
functions that CMS performs somewhat differently. To help you become 
familiar with the some of the CMS eguivalents (where they do exist) for 

05 terms and functions, see Figure 11. It lists some commonly-used OS 
terms and discusses how CMS handles the functions they imply. 
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OS Term/Function 
Cataloged procedure 

Data set 



Data Definition (DD) 
card 



Data Set Control 
Block (DSCB) 

EXEC card 



Job Control Language 
(JCL) 

Link-editing 



Load module 



Object module 



Partitioned data set 



STEPCAT,JOBCAT 



STEPLIB, JOBLIB 



Utility program 

Volume Table of 
Contents (VTOC) 



ens Equivalent 



EXEC files can execute command seguences 
similar to cataloged procedures, and provide 
for conditional execution based on return 
codes from previous steps. 

Data sets are called files in CHS; CHS files 
are always sequential but CHS simulates OS 
partitioned data sets. CHS reads and writes 
VSAH data sets. 

The FILEDEF command allows you to perform the 
functions of the DD statement to specify 
device types and output file dispositions. 

Information about a CHS disk file is contained 
in a File Status Table (FST) . 

To execute a program in CHS you specify only 
the name of the program if it is an EXEC, 
HODULE file, or CHS command. To execute TEXT 
files, use the LOAD and START commands. 

CHS and user-written commands perform the 
functions of JCL. 

The CHS LOAD command loads object decks (TEXT 
files) into virtual storage, and resolves 
external references; the GENHOD command 
creates absolute nonrelocatable modules. 

CHS HODULE files (resulting from the LOAD and 
GENHOD commands) are nonrelocatable. 

Language compiler output is placed in CHS 
files with a filetype of TEXT. 

CHS HACLIBs and TXTLIBs are the only CHS files 
that resemble partitioned data sets. 

VSAH catalogs can be assigned for jobs or job 
steps in CHS by using the special ddnames 
IJSYSCT and IJSYSUC when identifying catalogs. 

The GLOBAL command establishes macro and text 
libraries; you can indirectly provide job 
libraries by accessing and releasing CHS disks 
that contain the files and programs you need. 

Functions similar to those performed by the OS 
utility programs are provided by CHS commands. 

The list of files on a CHS disk is contained 
in a master file directory. 



Figure 11. OS Terms and CHS Equivalents 
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Using OS Data Sets in CMS 

You can have OS disks defined in your virtual machine configuration; 
they may be either entire disks or minidisks: their size and extent 
depends on their VM/370 directory entries. You can use partitioned and 
sequential data sets on OS disks in CMS. If you want, you can create 
CMS files from your OS data sets. If you have data sets on OS disks, 
you can read them from programs you execute in CMS, but you cannot 
update them. The CMS commands that recognize OS data sets on OS disks 
are listed in Figure 12. 



Command 
ACCESS 

ASSEMBLE 

DDR 

DLBL 

FILEDEF 



GLOBAL 



LISTDS 



MOVEFILE 



QUERY 



RELEASE 



STATE 



i 

Figure 12. 



Operation 



Makes the OS disk containing the data set available 
to your CMS virtual machine. 

Assembles an OS source program under CMS. 

Copies an entire OS disk to tape. 

Defines OS data sets for use with Access Method Services 
and VSAM files for program input/output. 

Defines the OS data set for use under CMS by associating 
an OS ddname with an OS data set name. Once defined, 
the data set can be used by an OS program running under 
CMS and can be manipulated by the other commands that 
support OS functions. 

Makes macro libraries available to the assembler. You can 
prepare an OS macro library for reference by the GLOBAL 
command by issuing a FILEDEF command for the data set and 
giving the data set a filetype of MACLIB. 

Lists information describing OS data sets residing on 
OS disks. 

Moves data records from one device to another device. Each 
device is specified by a ddname, which must have been 
defined via FILEDEF. You can use the MOVEFILE command to 
create CMS files from OS data sets. 

Lists (1) the files that have been defined with the 
FILEDEF and DLBL commands (QUERY FILEDEF, QUERY DLBL) , or 
(2) the status of OS disks attached to your virtual machine 
(QUERY DISK, QUERY SEARCH) . 

Releases an OS disk you have accessed (via ACCESS) from 
your CMS virtual machine. 

Verifies the existence of an OS data set on a disk. 
Before STATE can verify the existence of the data set, 
you must have defined it (via FILEDEF) . 

CMS Commands That Recognize OS Data Sets and OS Disks 
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ACCESS METHODS SUPPORTED BY CMS 

OS access methods are supported, to varying extents, by CMS. Under CMS, 
you can execute programs that use the OS data management macros that are 
supplied for these access methods: 

BEAM 
BFAM 
BSAM 
QSAM 
VSAM 

BP AM , BSAM, and 0. S AM : You can execute programs in CMS that read records 
from OS data sets using the BPAM, BSAM, or QSAM access methods. You 
cannot, however, write or update OS data sets that reside on OS disks. 

BDAM: CMS can neither read nor write OS data sets on OS disks using the 
BDAM access method. 

VSAM Files: CMS can read and write VSAM files on OS disks. For 
information on using VSAM under CMS, see "Section 10. Using Access 
Method Services and VSAM Under CMS and CMS/DOS." 



£S Simulated Data Sets 

If you want to test programs in CMS that create or modify OS data sets, 
you can write "OS simulated data sets." These are CMS files that are 
maintained on CMS disks, but in OS format rather than in CMS format. 
Since they are CMS files, you can edit, rename, copy, or manipulate them 
just as you would any other CMS file. Since they are in OS-simulated 
format, files with variable-blocked records may contain block and record 
descriptor words so that the access methods can manipulate them 
properly. 

The files that you create from OS programs do not necessarily have to 
be OS simulated data sets. You can create CMS files. The format of an 
output file depends on how you specify the filemode number when you 
issue the FILEDEF command to identify the file to CMS. If you specify 
the filemode number as 4, CMS creates a file that is in OS simulated 
data set format on a CMS disk. 

CMS can read and write OS simulated data sets using the BDAM, BPAM, 
BSAM, and QSAM access methods. 



J!§strictions for Reading OS Data Sets 

The following restrictions apply when you read OS data sets from OS 
disks under CMS: 

» Read-password-protected data sets are not read. 

«» BEAM and ISAM data sets are not read. 

» Multivolume data sets are read as single-volume data sets. 
End-of-volume is treated as end-of-file and there is no end-of-volume 
switching. 
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• Keys in data sets with keys are ignored; only the data is read. 

• User labels in user-labeled data sets are bypassed. 

Using the FILEDEF Command 

Whenever you execute an OS program under CMS that has input and/or 
output files, or you need to read an OS data set onto a CMS disk, you 
must first identify the files to CMS with the FILEDEF command. The 
FILEDEF command in CMS performs the same functions as the Data 
Definition (DD) card in OS job control language (JCL) : it describes the 
input and output files. 

When you enter the FILEDEF command, you specify: 

• The ddname 

• The device type 

• A file identification, if the device type is DISK 

• Options (if necessary) 

Some guidelines for entering these specifications follow. 



SPECIFYING THE DDNAME 

If the FILEDEF command is issued for a program input or output file, 
then the ddname must be the same as the ddname or file name specified 
for the file in the source program. For example, you have an assembler 
language source program that contains the line: 

INFILE DCB DDNAME=INPUTDD,MACRF=GL,DSORG=PS,RECFM=F,LRECL=80 

For a particular execution of this program, you want to use as your 
input file a CMS file on your A-disk that is named MYINPUT FILE, then, 
you must issue a FILEDEF for this file before executing the program: 

filedef inputdd disk myinput file a1 

If the input file you want to use is on an OS disk accessed as your 
C-disk, and it has a data set name of PAYROLL. RECORDS. AUGUST, then your 
FILEDEF command might be 

filedef inputdd d dsn payroll records august 



SPECIFYING THE DEVICE TYPE 

For input files, the device type you enter on the FILEDEF command 
indicates the device from which you want records read. It can be DISK, 
TERMINAL, READER (for input from real cards or virtual cards) , or TAPn 
(for tape) . Using the above example, if your input file is to be read 
from your virtual card reader, the FILEDEF command might be as follows: 

filedef inputdd reader 

Or, if you were reading from a tape attached to your virtual machine at 
virtual address 181 (TAP1): 
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filedef inputdd tapl 

For output files, the device you specify can be DISK, PRINTER, PUNCH, 
TAPn (tape), or TERMINAL. 

If you do not want any real I/O performed during the execution of a 
program for a disk input or output file, you can specify the device type 
as DUMMY: 

filedef inputdd dummy 



ENTERING FILE IDENTIFICATIONS 

If you are using a CMS disk file for your input or output, you specify 

filedef ddname disk filename filetype filemode 

The filemode field is optional; if you do not specify it, your A-disk is 
assumed. If you want an output file to be constructed in OS simulated 
data set format, you must specify the filemode number as 4. For 
example, a program contains a DCB for an output file with a ddname of 
OUTPUTDD, and you are using it to create a CMS file named DAILY OUTPUT 
on your B-disk: 

filedef outputdd disk daily output b4 

If your input file is an OS data set on an OS disk, you can identify 
it in several ways: 

• If the data set name has only two qualifiers, for example 
HEALTH. RECORDS, you can specify: 

filedef inputdd disk health records b1 

« If it has more than two qualifiers, you can use the DSN keyword and 
enter: 

filedef inputdd b1 dsn health records august 1974 

Or you can request a prompt for a complete data set name: 

filedef inputdd b1 dsn ? 
ENTER DATA SET NAME: 
health. records. august. 1974 

Note: When you enter a data set name using the DSN keyword, either 
with or without a request for prompting, you should omit the device 
type specification of DISK, unless you want to assign a CMS file 
identifier, as in the example below. 

• You can also relate an OS data set name to a CMS file identifier: 

filedef inputdd disk ossim file d dsn monthly records 

Then you can refer to the OS data set MONTHLY. RECORDS by using the 
CMS file identifier, OSSIM FILE: 

state ossim file c 

When you do not issue a FILEDEF command for a program input or output 
file, or if you enter only the ddname and device type on the FILEDEF 
command, such as: 
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filedef oscar disk 

then CMS issues a default file definition, as follows: 

FILEDEF ddname DISK FILE ddname A1 

where ddname is the ddname you assigned in the DDNAME operand of the DCB 
■aero in your program or on the FILEDEF command. For example, if you 
assign a ddname of OSCAR to an output file and do not issue a FILEDEF 
command before you execute the program, then the CMS file FILE OSCAR A1 
is created when you execute the program. 



SPECIFYING OPTIONS 

The FILEDEF command has many options; those mentioned below are a 
sampling only. For complete descriptions of all the options of the 
FILEDEF command, see the VM/370: CMS Command and Macro Reference. 

SIjOCK, LRECL, RECFM, DSORG: If you are using the FILEDEF command to 
relate a data control block (DCB) in a program to an input or output 
file, you may need to supply some of the file format information, such 
as the record length and block size, on the FILEDEF command line. For 
example, if you have coded a DCB macro for an output file as follows: 

OUTFILE DCB DDNAME=OUT,MACRF=PM,DSORG=PS 

then, when you are issuing a FILEDEF for this ddname, you must specify 
the format of the file. To create an output file on disk, blocked in OS 
simulated data set format, you could issue: 

filedef out disk myoutput file aU (recfm fb lrecl 80 block 1600 

To punch the output file onto cards, you would issue 

filedef out punch (lrecl 80 recfm f 

You must supply file format information on the FILEDEF command line 
whenever it is not supplied on the DCB macro, except for existing disk 
files. 

PERM: Usually, when you execute one of the language processors, all 
existing file definitions are cleared. If the development of a program 
requires you to recompile and re-execute it frequently, you might want 
to use the PERM option when you issue file definitions for your input 
and output files. For example: 

cp spool punch to * 

filedef indd disk test file a1 (lrecl 80 perm 

filedef outdd punch (lrecl 80 perm 

In this example, since you spooled your virtual punch to your own 
virtual card reader, output files are placed in your virtual reader. You 
can either read or delete them. 

All file definitions issued with the PERM option stay in effect until 
you log off, specifically clear those definitions, or redefine them: 

filedef indd clear 

filedef outdd tapl (lrecl 80 

In the above example, the definition for INDD is cleared; OUTDD is 
redefined as a tape file. 
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When you issue the command 

filedef * clear 

all file definitions are cleared, except those you enter with the PERM 
option. 

When a program abends, or when you issue the HX Immediate command, 
all file definitions are cleared, including those entered with the PERM 
option. 

DISP MOD: When you issue a FILEDEF command for an output file and assign 
it a CMS file identifier that is identical to that of an existing CMS 
file, then when anything is written to that ddname the existing file is 
replaced by the new output file. If you want, instead, to have new 
records added to the bottom of the existing file, you can use the DISP 
MOD option: 

filedef outdd disk new update a1 (disp mod 

MEMBER: If the file you want to read is a member of an OS partitioned 
data set (or a CMS MACLIB or TXTLIB) , you can use the MEMBER option to 
specify the membername, for example 

filedef test c dsn sysl maclib (member test 

defines the member TEST from the OS macro library SYS1.MACLIB. 



Creating CMS Files From OS Data Sets 

If you have data sets on OS disks, or on tapes or cards, you can copy 
them into CMS files so that you can edit, modify, or manipulate them 
with CMS commands. The CMS MOVEFILE command copies OS (or CMS) files 
from one device to another. You can move data sets from any valid input 
device to any valid output device. 

Before using the MOVEFILE command, you must define the input and 
output data sets or files and assign them ddnames using the FILEDEF 
command. If you use the ddnames INMOVE and OUTMOVE, then you do not 
need to specify the ddnames when you issue the MOVEFILE command. For 
example, the following seguence of commands copies a CMS disk file into 
your virtual card punch: 

filedef inmove disk diskin file a1 

filedef outmove punch 

movefile 

The result of these commands is effectively the same as if you had 
issued the command 

punch diskin file (noheader 

The example does, however, illustrate the basic relationship between the 
FILEDEF and MOVEFILE commands. In addition to the MOVEFILE command, if 
the OS input data set is on tape or cards, you can use the TAPPDS or 
READCARD command to create CMS files. These are also discussed below. 

COPYING SEQUENTIAL DATA SETS FROM DISK: The MOVEFILE command copies a 
seguential OS disk data set from a read-only OS disk into an integral 
CMS file on a CMS read/write disk. You use FILEDEF commands to identify 
the input file disk mode and data set name: 
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filedef inmove d dsn sales manual 
the CMS output file's disk location and fileid: 

filedef outmove disk sales manual a1 
and then you issue the MOVEFILE command: 

movefile 

COPYING PARTITIONED DATA SETS FROM DISK: The MOVEFILE command can copy 
partitioned data (PDS) into CMS disk files, and create separate CMS 
files for each member of the data set. You can have the entire data set 
copied, or you can copy only a selected member. For example, if you 
have a partitioned data set named ASSEMBLE. SOURCE whose members are 
individual assembler language source files, your input file definition 
might be: 

filedef inmove c1 dsn assemble source 

To create individual CMS ASSEMBLE files, you would issue the output file 
definition as: 

filedef outmove disk gprint assemble a1 

Then use the PDS option of the MOVEFILE command: 

movefile (pds 

When the CMS files are created, the filetype on the output file 
definition is used for the filetype and the member names are used 
instead of the CMS filename you specified. 

If you want to copy only a single member, you can use the MEMBER 
option of the FILEDEF command: 

filedef inmove disk assemble source c (member gprint 

and omit the PDS option on the MOVEFILE command: 

movefile 

Figure 13 summarizes the various ways that you can create CMS files 
from OS data sets. 
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1 Input File: An OS sequential data set named: COMPUTE. TEST. RECORDS | 


| Source | CMS Command Examples 1 CMS Output File | 


| Disk: | filedef indd d dsn compute test records | COMPUTE RECORDS A1 | 
| OS R/O | filedef outdd disk compute records a1 I I 
| C-disk | movefile indd outdd I I 


| Tape: | filedef inmove tapl (lrecl 80 | TEST RECORDS A1 | 
| 181 | filedef outmove disk test records al | 1 
| | movefile I I 


I | tappds newtest compute (nopds | NEWTEST COMPUTE A1 | 


| Cards | filedef cardin reader I COMPUTE CARDS A1 | 
| | filedef diskout disk compute cards a1 | I 
| | movefile cardin diskout I I 


| | readcard compute test I COMPUTE TEST A1 | 




| Input file: OS partitioned data set named: TEST. CASES I 
| Members named: SIMPLE, COMPLEX, MIXED I 


| Source | CMS Command Examples I CMS Output File (s) | 


| Disk: | filedef infile disk test cases cl I SIMPLE TESTCASE A1 | 
| OS R/O | filedef outfile disk new testcase a1 | COMPLEX TESTCASE A1 | 
| C-disk | movefile infile outfile (pds | MIXED TESTCASE | 

| | filedef in d dsn test cases (member simple | FILE RUN A1 I 
| | filedef run disk | I 
| | movefile in run I I 


| Tape: | tappds * testrun (tap2 I SIMPLE TESTRUN A1 | 
| 182 | I COMPLEX TESTRUN A1 | 
| | | MIXED TESTRUN A1 | 



Figure 13. Creating CMS Files From OS Data Sets 



Using CMS Libraries 

CMS provides two types of libraries to aid in OS program development: 

• Macro libraries contain macro definitions and/or copy files 

• Text, or program libraries contain relocatable object programs 

(compiler output) 

These CMS libraries are like OS partitioned data sets; each has a 
directory and members. Since they are not like other CMS files, you 
create, update, and use them differently than you do other CMS files. 
Macro libraries are discussed below; text libraries are discussed under 
"TEXT Libraries (TXTLIBs) •■ later in this section. 

A CMS macro library has a filetype of MACLIB. You can create a MACLIB 
from files with filetypes of MACRO or COPY. A MACBO file may contain 
macro definitions; COPY files contain predefined source statements. 

When you want to assemble or compile a source program that uses macro 
or copy definitions, you must ensure that the library containing the 
code is identified before you invoke the compiler. Otherwise, the 
library is not searched. You identify libraries to be searched using the 
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GLOBAL command. For example, if you have two MACLIBs that contain your 
private macros and copy files whose names are TESTMAC MACLIB and 
TESTCOPY MACLIB, you would issue the command 

global maclib testmac testcopy 

The libraries you specify on a GLOBAL command line are searched in the 
order you specify them. A GLOBAL command remains in effect for the 
remainder of your terminal session, until you issue another GLOBAL 
MACLIB command or re-IPL CMS. To find out what macro libraries are 
currently available for searching, issue the command 

guery maclib 

You can reset the libraries or the search order by reissuing the GLOBAL 
command. 



THE MACLIB COMMAND 

The MACLIB command performs a variety of functions. You use it to: 

• Create the MACLIB (GEN function) 

• Add, delete, or replace members (ADD, DEL, and REP functions) 

• Compress the MACLIB (COMP function) 

• List the contents of the MACLIB (MAP function) 

Descriptions of these MACLIB command functions follow. 

GEN Function: The GEN (generate) function creates a CMS macro library 
from input files specified on the command line. The input files must 
have filetypes of either MACHO or COPY. For example: 

maclib gen osmac access time put regegu 

creates a macro library with the file identifier OSMAC MACLIB A1 from 
macros existing in the files with the file identifiers: 

ACCESS (MACRO), TIME /MACRO), PUT /MACRO), and REGEQU J MACRO) 
(COPY / {copy / |COPY j \COPY j 

If a file named OSMAC MACLIB A1 already exists, it is erased. 

Assume that the files ACCESS MACRO, TIME COPY, POT MACRO, and REGEQU 
COPY exist and contain macros in the following form: 

ACCESS MACRO TIME COPY PUT MACRO REGEQU COPY 



GET *COPY TTIMER PUT XREG 

TTIMER 
PUT *COPY STIMER YREG 

STIMER 

The resulting file, OSMAC MACLIB A1, contains the members: 

GET STIMER 
PUT PUT 
TTIMER REGEQU 

The PUT macro, which appears twice in the input to the command, also 
appears twice in the output. The MACLIB command does not check for 
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duplicate macro names. If, at a later time, the POT macro is requested 
from OSMAC MACLIB, the first PUT macro encountered in the directory is 
used . 

When COPY files are added to MACLIBs, the name of the library member 
is taken from the name of the COPY file, or from the *COPY statement, as 
in the file TIME COPY, above. Note that although the file REGEQD COPY 
contained two macros, they were both included in the MACLIB with the 
name BEGEQU. When the input file is a MACRO file, the member name (s) are 
taken from macro prototype statements in the MACRO file. 

1I?P Function; The ADD function appends new members to an existing macro 
library. For example, if OSMAC MACLIB A1 exists as created in the 
example in the explanation of the GEN function and the file DCB COPY 
exists as follows: 

*COPY DCB 

DCB macro definition 
♦COPY DCBD 

DCBD macro definition 

if you issue the command 

maclib add osmac deb 

the resulting OSMAC MACLIB A1 contains the members: 

GET POT 

POT REGEQU 

TTIMER DCB 

STIMER DCBD 

1J?1 Junction: The REP (replace) function deletes the directory entry for 
the macro definition in the files specified. It then appends new macro 
definitions to the macro library and creates new directory entries. For 
example, assume that a macro library MYMAC MACLIB contains the members 
A, B, and C, and that the following command is entered: 

maclib rep mymac a c 

The files represented by file identifiers A MACRO and C MACRO each have 
one macro definition. After execution of the command, MYMAC MACLIB 
contains members with the same names as before, but the contents of A 
and C are different. 

QUli function: The DEL (delete) function removes the specified macro name 
from the macro library directory and compresses the directory so there 
are no unused entries. The macro definition still occupies space in the 
library, but since no directory entry exists it cannot be accessed or 
retrieved. If you attempt to delete a macro for which two macro 
definitions exist in the macro library, only the first one encountered 
is deleted. For example: 

maclib del osmac get put ttimer deb 

deletes macro names GET, POT, TTIMER, and DCB from the directory of the 
macro library named OSMAC MACLIB. Assume that OSMAC exists as in the ADD 
function example. After the above command, OSMAC MACLIB contains the 
following members: 

STIMER 
POT 

REGEQU 
DCBD 
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CQMP Function: Execution of a M ACL IB command with the DEL or REP 
functions can leave unused space within a macro library. The COMP 
(compress) function removes any macros that do not have directory 
entries. This function uses a temporary file named MACLIB CMSUT1. For 
example, the command: 

maclib comp mymac 

compresses the library MYMAC MACLIB. 

Of lection: The MAP function creates a list containing the name of 
each macro in the directory, the size of the macro, and its position 
within the macro library. If you want to display a list of the members 
of a MACLIB at the terminal, enter the command 

maclib map mylib (term 

The default option, DISK, creates a file on your A-disk, which has a 
filetype of MAP and a filename corresponding to the filename of the 
MACLIB. If you specify the PRINT option, the list is spooled to your 
virtual printer, as well as being written onto disk. 



Manipulating MACLIB Members 

The following CMS commands have MEMBER options, which allow you to 
reference individual members of a MACLIB: 

• PRINT (to print a member) 

• PUNCH (to punch a member) 

• TYPE (to display a member) 

• FILEDEF (to establish a file definition for a member) 

You can use the CMS Editor to create MACRO and COPY files and then 
use the MACLIB command to place the files in a library. Once they are 
in a library, you can erase the original files. 

To extract a member from a macro library, you can use either the 
PUNCH or the MOVEFILE command. If you use the PUNCH command you can 
spool your virtual card punch to your own virtual reader: 

cp spool punch to * 
then punch the member: 

punch testmac maclib (member get noheader 
and read it back onto disk: 

readcard get macro 

In the above example, the member was punched with the NOHEADER option of 
the PUNCH command, so that a name could be assigned on the READCARD 
command line. If a header card had been created for the file, it would 
have indicated the filename and filetype as GET MEMBER. 

If you use the MOVEFILE command, you must issue a file definition for 
the input member name and the output macro or copy name before entering 
the MOVEFILE command: 

filedef inmove disk testcopy maclib (member enter 

filedef outmove disk enter copy a 

movefile 
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This example copies the member ENTER from the macro library TESTCOPY 
MACLIB into a CMS file named ENTER COPY. 

When you use the PUNCH or MOVEFILE commands to extract members from 
CHS MACLIBs, each member is followed by a // record, which is a MACLIB 
delimiter. You can edit the file and use the DELETE subcommand to 
delete the // record. 



Sistem MACLIBs 

The macro libraries that are on the system disk contain CMS and OS 
assembler language macros that you may want to use in your programs: 

• CMSLIB MACLIB contains the CMS macros. 

• OSMACRO MACLIB contains the OS macros that CMS simulates. 

• OSMACR0 1 MACLIB contains the macros CMS does not simulate. (You can 
assemble programs in CMS that contain these macros, but you must 
execute them in an OS virtual machine.) 

• TSOMAC MACLIB contains TSO macros. 

• DOSMACRO MACLIB contains macros used in CMS/DOS. 

To obtain a list of the macros in any of these libraries, use the MAP 
function of the MACLIB command. 



USING OS MACRO LIBRARIES 

If you want to assemble source programs that contain macro statements 
that are defined in macro libraries on your OS disks, you can use the 
FILEDEF command to identify them to CMS so that you can name them when 
you issue the GLOBAL command. For example, the commands 

filedef cmslib disk temp maclib c dsn test asm macros 
global maclib temp 

allow you to access the macro library TEST. ASM. MACROS on the OS disk 
accessed as your C-disk. 

When you issue a FILEDEF command for an assembler language macro 
library you must use a ddname of CMSLIB; and you must provide a CMS file 
identifier for the OS data set. In the example above, the OS macro 
library TEST. ASM. MACROS is given the CMS file identifier TEMP MACLIB. 

If you want to use more than one OS macro library you must issue a 
FILEDEF command for each library using the ddname CMSLIB and specifying 
the CONCAT option. For example: 

Siledef cmslib disk asp 1 maclib * dsn aspl macros rl (concat recfm fb block 3360 lrecl 80 

filedef cmslib disk asp2 maclib * dsn asp2 macros rl (concat 

liiledef cmslib disk sysl maclib * 

global maclib aspl asp2 sysl osmacro cmslib 

The GLOBAL command establishes the search order of the libraries as: 
ASPL MACROS. RL, ASP2. MACROS. RL, SYS1.MACLIB, OSMACRO MACLIB, and CMSLIB 
MACLIB. Note that the third library specified is entered in an 
abbreviated form. You can use this form when the data set name of the 
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macro library has only two qualifiers and the second qualifier is 
MACLIB; thus, the equivalency is established between SYS1.MACLIB and the 
CMS file identifier SYS1 MACLIB. 

The file format information describes the macro libraries to CMS; 
when you are concatenating OS macro libraries, they must all be in the 
same format, since the options entered on the first FILEDEF command are 
applied to all the libraries. 

If you are using only one OS macro library in addition to CMS MACLIBs 
you can enter either 

filedef cmslib disk libl maclib * dsn sysl maclib (concat 
global maclib libl cmslib 

— or — 

filedef cmslib disk libl maclib * dsn sysl maclib 
global maclib libl cmslib 

To identify libraries for use with the language processors, you must 
use the ddname SYSLIB. 



Using OS Macros Under CMS 

You can assemble and execute programs under CMS that use OS macros. 
Figure 14 lists the OS macros that CMS simulates. The macros that are 
are listed as "Effective no-op" and "no-op" are macros that are not 
supported in CMS; you can assemble programs that contain these macros, 
but when you execute them in CMS the macro functions are not performed. 
To execute these programs, you must run them in an OS virtual machine. 

For a more detailed description of how CMS simulates the functions of 
these macros, and to see whether any particular function of a macro is 
not supported, see the VM£370: System Programmer 1 s Guide. 



Assembling Programs in CMS 

To assemble assembler language source programs into object module 
format, you can use the ASSEMBLE command, and specify assembler options 
on the command line, for example 

assemble myfile (print 

assembles a source program named MYFILE ASSEMBLE and directs the output 
listing to the printer. All of the ASSEMBLE command options are listed 
in the VM/370: CMS Command and Macro Reference. 

When you invoke the ASSEMBLE command specifying a file with the 
filetype of ASSEMBLE, CMS searches all of your accessed disks, using the 
standard search order, until it locates the specified file. When the 
assembler creates its output listing and text deck, it creates files 
with filetypes of LISTING and TEXT, and writes them onto disk according 
to the following priorities: 

1. If the source file is on a read/write disk, the TEXT and LISTING 
files are written onto that disk. 
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Macro 
ABEND 


SVC No 
13 


ATTACH 


42 


BLDL 


18 


BSP 


69 


CHAP 


44 


CHECK 


— 


CHKPT 


63 


CLOSE 


20 


DCB 


— 


DCBD 


— 


DELETE 


09 


DEQ 


48 


DETACH 


62 


DEVTYPE 


24 


EHQ 


56 


EXTRACT 


40 


FIND 


18 


FREEDBUF 


57 


FREEMAIN 


05 


FREEMAIN 


10 


FREEPOOL 


— 


GET 


— 


GETMAIN 


04 


GETMAIN 


10 


GETPOOL 


— 


IDENTIFY 


41 


LINK 


06 


LOAD 


08 


NOTE 


— 


OPEN 


19 


OPENJ 


22 


POINT 


— 


POST 


02 


PUT 


— 


RDJFCB 


64 


READ 


— 


RETURN 


— 


SAVE 


— 


SNAP 


51 


SPIE 


14 



STAE 



60 



STAX 


96 


STIMER 


47 


STOW 


21 


SYNADAF 


— 


SYNADRLS 


— 


TCLEARQ 


94 


TCLOSE 


23 


TGET/TPUT 


93 


TIME 


11 


TRKBAL 


25 


TTIMER 


46 


WAIT 


01 


WRITE 


— 


WTO/WTOR 


35 


XCTL 


07 



XDAP 



00 



Function 

Terminate processing 

Effective LINK 

Build a directory list for a PDS 

Back up a record on a tape or disk 

Effective no-op 

Verify READ/WRITE macro completion 

Effective no-op 

Deactivate a data file 

Construct a data control block 

Generate a DSECT for a data control block 

Delete a loaded phase 

Effective no-op 

Effective no-op 

Obtain device-type characteristics 

Effective no-op 

Effective no-op 

Locate a member of a partitioned data set 

Release a free storage buffer 

Release user-acquired storage 

Manipulate user free storage 

Simulate as SVC 10 

Read system-blocked data (QSAM) 

Conditionally acquire user storage 

Manipulate user free storage 

Simulate as SVC 10 

Add entry to loader table 

Link control to another phase 

Read a phase into storage 

Manage data set positioning 

Activate a data file 

Activate a data file 

Manage data set positioning 

Post the I/O completion 

Write system-blocked data (QSAM) 

Obtain information from FILEDEF command 

Access system— record data 

Return from a subroutine 

Save program registers 

Dump specified areas of storage 

Allow processing program to 

handle program interrupts 
Allow processing program to 

decipher abend conditions 
Create an attention exit block 
Set timer 

Manipulate partitioned directories 
Provide SYNAD analysis function 
Release SYNADAF message and save areas 
Clear terminal input queue 
Temporarily deactivate a data file 
Read or write a terminal line 
Get the time of day 
no-op 

Access or cancel timer 
Wait for an I/O completion 
Write system— record data 
Communicate with the terminal 
Delete, then link control to another 

load phase 
Read or write direct access volumes 



i 



Figure 14. OS Macros Simulated by CMS 
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2. If the source file is on a read-only extension of a read/write 
disk, the TEXT and LISTING files are written onto the parent disk. 

3. If the source file is on any other read-only disk, the TEXT and 
LISTING files are written onto the A-disk. 

In all of the above cases, the TEXT and LISTING files have a filename 
that is the same as the input ASSEMBLE file. 

The input and output files used by the assembler are assigned by 
FILEDEF commands that CMS issues internally when the assembler is 
invoked. If you issue a FILEDEF command using one of the assembler 
ddnames before you issue the ASSEMBLE command, you can override the 
default file definitions. 

The ddname for the source input file (SYSIN) is ASSEMBLE. If you 
enter 

filedef assemble reader 
assemble sample 

then the assembler reads your input file from your card reader, and 
assigns the filename SAMPLE to the output TEXT and LISTING files. 

You could assemble a source file directly from an OS disk by entering 

filedef assemble disk myfile assemble b4 dsn os source file 
assemble myfile 

In this example, the CMS file identifier MYFILE ASSEMBLE is assigned to 
the data set OS. SOURCE. FILE and then assembled. 

LISTING and TEXT are the ddnames assigned to the SYSPRINT and SYSLIN 
output of the assembler. You might assign file definitions to override 
these defaults as follows: 

filedef listing disk assemble listfile a 
filedef text disk assemble textfile a 
assemble source 

In this example, output from the assembly of the file, SOURCE ASSEMBLE, 
is written to the files, ASSEMBLE LISTFILE and ASSEMBLE TEXTFILE. 

The ddnames PUNCH and CMSLIB are used for SYSPUNCH and SYSLIB data 
sets. PUNCH output is produced when you use the DECK option of the 
ASSEMBLE command. The default file definition for CMSLIB is the macro 
library CMSLIB MACLIB, but you must still issue the GLOBAL command if 
you want to use it. 



Executing Programs 

After you have assembled or compiled a source program you can execute 
the TEXT files that were produced by the assembly or compilation. You 
■ay not, however, be able to execute all your OS programs directly in 
CMS. There are a number of execution-time restrictions placed on your 
virtual machine by VM/370. You cannot execute a program that uses: 

• Multitasking 

• More than one partition 

• Teleprocessing 

• ISAM macros to read or write files 
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The above is only a partial list, representing those restrictions with 
which you might be concerned. For a complete list of restrictions, see 
the VM/370: Planning and System Generation Guide. 



EXECUTING TEXT FILES 

TEXT files, in CBS, are relocatable, and can be executed simply by 
loading them into virtual storage with the LOAD command and using the 
START command to begin execution. For example, if you have assembled a 
source prograa named CREATE, you have a file named CREATE TEXT. You can 
issue the command 

load create 

which loads the relocatable object file into storage, and then, to 
execute it, you can issue the START command: 

start 

In the case of a simple program, as in the above example, you can 
load and begin execution with a single command line, using the START 
option of the LOAD command: 

load create (start 

When you issue the START command or LOAD command with the START 
option, control is passed to the first 'entry point in your program. If 
you have more than one entry point and you want to begin execution at an 
entry point other than the first, you can specify the alternate entry 
point or CSECT name on the START command: 

start create2 

When you issue the LOAD command specifying the filename of a TEXT file, 
CMS searches all of your accessed disks for the specified file. 

If your program expects a parameter list to be passed (via register 
1}i , you can specify the arguments on the START command line. If you 
enter arguments, then you must specify the entry point: 

start * namel 

When you specify the entry point as an asterisk (*) it indicates that 
you want to use the default entry point. 



J5.®Ji:5i:J53 l££3it and Output Files 

You can issue the FILEDEF command to define input and output files any 
time before you begin program execution. You can issue all your file 
definitions before loading any TEXT files, or issue them during the 
loading process. You can find out what file definitions are currently 
in effect by issuing the FILEDEF command with no operands: 

f iledef 

You can also use the FILEDEF operand of the QUERY command. 
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TEXT LIBRARIES (TXTLIBS) 

You may want to keep your TEXT files in text libraries, that have a 
filetype of TXTLIB. Like HACLIBs, TXTLIBs have a directory and members. 
TXTLIBs are created and modified by the TXTLIB command, which has 
functions similar to the HACLIB command: 

• The GEN function creates the TXTLIB. 

• The ADD function adds members to the TXTLIB. 

• The DEL function deletes members and compresses the TXTLIB. 

• The HAP function lists members. 

There is no REP function; you must use a DEL followed by an ADD to 
replace an existing member. The CHS commands that recognize MACLIBs as 
special filetypes also recognize TXTLIBs, and allow you to display, 
print, or punch TXTLIB members. 

The TXTLIB command reads the object files as it writes them into the 
library, and creates a directory entry for each entry point or CSECT 
name. If you have a TEXT file named HYPROG, which has a single routine 
named BEGIN, and create the TXTLIB named TESTLIB as follows: 

txtlib gen testlib myprog 

TESTLIB contains no entry for the name HYPROG; you must specify the 
membername BEGIN to reference this TXTLIB member. 

When you want to load members of TXTLIBs into storage to execute them 
(just as you execute TEXT files), you must issue the GLOBAL command to 
identify the TXTLIB: 

global txtlib testlib 
load begin (start 

When you specify more than one TXTLIB on the GLOBAL command line, the 
order of search is established for the TXTLIBs. However, if the AUTO 
option is in effect (it is the default) , CHS searches for TEXT files 
before searching active TXTLIBs. 

When the TXTLIB command processes a TEXT file, it writes an LDT 
(loader terminate) card at the end of the TEXT file, so that when a load 
request is issued for a TXTLIB member, loading terminates at the end of 
the member. If you add OS linkage editor control statements to the TEXT 
file (using the CHS Editor) before you issue the TXTLIB command to add 
the file to a TXTLIB, the control statements are processed as follows: 

NAHE: A NAHE statement causes the TXTLIB command to create the directory 
entry for the member using the specified name. Thereafter, when you want 
to load that member into storage or delete it from the TXTLIB you must 
refer to it by the name specified on the NAHE statement. 

ENTRY: If you use an ENTRY statement, the entry point you specify is 
validated and checked for a duplicate. If the entry point name is valid 
and there are no duplicates in the TEXT file, the entry name is written 
in the LDT card. Otherwise, an error message is issued. When this 
member is loaded, execution begins at the entry point specified. (See 
"Determining Program Entry Points," below.) 

ALIAS: An entry is created in the directory for the ALIAS name you 
specify. A maximum of 16 alias names can be used in a single text deck. 
You may load the single member and execute it by referring to the alias 
name, but you cannot use the alias name as the object of V-type address 
constant (VCON) , because the address of the member cannot be resolved. 
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SKTSSI: Information you specify on the SETSSI cara is written in bytes 
26 through 33 of the LDT card. 

All other OS linkage editor control statements are ignored by the 
TXTLIB command and written into the TXTLIB member. When you attempt to 
load the member, the CMS loader flags these cards as invalid. 



RKSOLVING EXTERNAL REFERENCES 

There is no real linkage editor in CMS; the link-edit function, that of 
locating external references and loading additional object modules into 
storage, is performed by the CMS loader. The CMS loader loads files 
into storage as a result of a LOAD or INCLUDE command, or when you issue 
a dynamic load reguest from a program (using the OS macros LOAD, LINK, 
or XCTL) . 

When a file is loaded, the leader checks for unresolved references; 
if there are any, the loader searches your disks for TEXT files with 
filenames that match the external entry name. When it finds a match, it 
loads the TEXT file into storage. If a TEXT file is not found, the 
loader searches any available TXTLIBs for members that match, and loads 
them when it does. 

If there are still unresolved references, for example, if you load a 
program that calls routines PRINT and ANALYZE but the loader cannot 
locate them, you receive the message: 

THE FOLLOWING NAMES ARE UNDEFINED: 
PRINT 
ANALYZE 

You can issue the INCLUDE command to load additional TEXT files or 
TXTLIB members into storage so the loader can resolve any remaining 
references. For example, if you did not identify the TXTLIB that 
contains the routines you want to call, you may enter the GLOBAL command 
followed by the INCLUDE command: 

global txtlib newlib 
include print analyze (start 

This situation might also occur if you have TEXT files with filenames 
that are different from the CSECT names; you must explicitly issue LOAD 
and INCLUDE commands for these files. 

At execution time, if there are still any unresolved references, 
their addresses are all set to by the loader, so any attempt to 
address them in a program may result in a program check. 



lk§. LOAD and INCLUDE Commands 

The INCLUDE command has the same format and option list (with one 
exception) as the LOAD command. The main difference is that when you 
issue the INCLUDE command the loader tables are not reset; if you issue 
two LOAD commands in succession, the second LOAD command cancels the 
effect of the first, and the pointers to the files loaded are lost. 

Conversely, the INCLUDE command, which you must issue when you want 
to load additional files into storage, should not be used unless you 
have just issued a LOAD command. You may specify as many INCLUDE 
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commands as necessary following a LOAD command to load files into 
storage. 



CONTROLLING THE CMS LOADER 

The LOAD and INCLUDE commands allow you to specify a number of options. 
You can: 

• Change the entry point to which control is to be passed when 
execution begins (RESET option) . 

• Specify the location in virtual storage at which you want the files 
to be loaded (ORIGIN option) . 

• Control how CMS resolves references and handles duplicate CSECT names 
(AUTO, LIB, and DUP options). 

• Clear storage to binary zeros before loading files (CLEAR option) . 

When the LOAD and INCLUDE commands execute, they produce a load map, 
indicating the entry points loaded and their virtual storage locations. 
You may find this load map useful in debugging your programs. If you do 
not specify the NOMAP option, the load map is written onto your A-disk, 
in a file named LOAD MAP A5. Each time you issue the LOAD command, the 
old file LOAD MAP is erased and the new load map replaces it. If you do 
not want to produce a load map, specify the NOMAP option. 

You can find details about these, and other options under the 
discussion of the LOAD command in VM/370: CMS Command and Macro 
Reference. "~ 



!&ader Control Statements 

In addition to the options provided with the LOAD and INCLUDE commands 
that assist you in controlling the execution of TEXT files, you can also 
use loader control statements. These can be inserted in TEXT files, 
using the CMS Editor. The loader control statements allow you to: 

• Set the location counter to specify the address at which the next 
TEXT file is to be loaded (SLC statement) . 

• Modify instructions and constants in a TEXT file, and change the 
length of the TEXT file to accomodate modifications (Replace and 
Include Control Section statements) . 

• Change the entry point (ENTRY statement) . 

• Nullify an external reference so that it does not receive control 
when it is called, and you do not receive an error message when it is 
encountered (LIBRARY statement) . 

These statements are also described under the LOAD command in VM/37 : 
CMS Command and Macro Refe^enc^. 
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Determininc| Eioaran Entr.y, Points 

When you load a single TEXT file or a TXTLIB member into storage for 
execution, the default entry point is the first CSECT name in the object 
file loaded. You can specify a different entry point at which to start 
execution either on the LOAD (or INCLUDE) command line with the RESET 
option: 

load myprog (reset beta 

where BETA is the alternate entry point of your program, or you can 
specify the entry point on the START command line: 

start beta 

When you load multiple TEXT files (either explicitly or implicitly, 
by allowing the loader to resolve external references) , you also have 
the option of specifying the entry point on the LOAD, INCLUDE, or START 
command lines. 

If you do not specifically name an entry point, the loader determines 
the entry point for you, according to the following hierarchy: 

11. An entry point specified on the START command 

2. The last entry specified with the RESET option en a LOAD or INCLUDE 
command 

3. The name on the last ENTRY statement that was read 

4. The name on the last LDT statement that contained an entry name 
that was read 

5. The name on the first assembler- or compiler-produced END statement 
that was read 

6. The first byte of the first control section loaded 

For example, if you load a series of TEXT files that contain no 
control statements, and do not specify an entry point on the LOAD, 
INCLUDE, or START commands, execution begins with the first file that 
you loaded. If you want to control the execution of program subroutines, 
you should be aware of this hierarchy when you load programs or when you 
place them in TXTLIBs. 

An area of particular concern is when you issue a dynamic load (with 
the OS LINK, LOAD, or XCTL macros) from a program, and you call members 
of CMS TXTLIBs. The CMS loader determines the entry point of the called 
program, and returns the entry point to your program. If a TXTLIB member 
that you load has a VCON to another TXTLIB member, the LDT card from the 
second member may be the last LDT card read by the loader. If this LDT 
card specifies the name of the second member, then CMS may return that 
entry point address to your program, rather than the address of the 
first member. 



CREATING PROGRAM MODULES 

When your programs are debugged and tested, you can use the LOAD and 
INCLUDE commands, in conjunction with the GENMOD command, to create 
program modules. A module is a nonrelocatable file whose external 
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references have been resolved. In CMS, these files must have a filetype 
of MODULE. 

To create a program module, load the TEXT files or TXTLIB members 
into storage and issue the GENMOD command: 

load create analyze print 
geninod process 

In this example, PROCESS is the filename you are assigning the 
module; it will have a filetype of MODULE. You could use any name; if 
you use the ijame of an existing MODULE file, the old one is replaced. 

To execute the program composed of the source files CREATE, ANALYZE, 
and PRINT, enter: 

process 

If PROCESS reguires input and/or output files, you will have to define 
these files before PROCESS can execute properly; if PROCESS expects 
arguments passed to it, you can enter them following the MODULE name, 
for example 

process testl 

For more information on creating program modules, see "Section 13. 
Programming for the CMS Environment." 



USING EXEC PROCEDURES 

During your program development and testing cycle, you may want to 
create EXEC procedures to contain seguences of CMS commands that you 
execute freguently. For example, if you need a number of MACLIBs, 
TXTLIBs, and file definitions to execute a particular program, you might 
have an EXEC procedure as follows: 

&CONTROL ERROR TIME 

SERROR 8EXIT &RETCODE 

GLOBAL MACLIB TESTLIB OSMACRO 0SMACR01 

ASSEMBLE TESTA 

PRINT TESTA LISTING 

GLOBAL TXTLIB TESTLIB PROGLIB 

ACCESS 200 E 

SBEGSTACK 

OS. TEST3. STREAM. BETA 

SEND 

FILEDEF INDD1 E DSN ? 

FILEDEF INDD2 READER 

FILEDEF OUTFILE DISK TEST DATA A1 

LOAD TESTA (START 

&IF &RETCODE = 100 &GOTO -RET100 

8IF 8RETC0DE = 200 &GOTO -RET200 

&EXIT &RETCODE 

-RET100 6CONTINUE 



-RET200 SCONTINUE 
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The SCONTBOL and SEBBOB control statements in the EXEC procedure 
ensure that if an error occurs during any part of the EXEC, the 
remainder of the EXEC does not execute, and the execution summary of the 
EXEC indicates the command that caused the error. 

Note that for the FILEDEF command entered with the DSN ? operand, 
you must stack the response before issuing the FILEDEF command. In this 
example, since the OS data set name has more than 8 characters, you must 
use the &BEGSTACK control statement to stack it. If you use the &STACK 
control statement, the EXEC processor truncates all words to 8 
characters. 

When your program is finished executing, the EXEC special variable 
&BETCODE indicates the contents of general register 15 at the time the 
program exited, you can use this value to perform additional steps in 
your EXEC procedure. Additional steps are indicated in the preceding 
example by ellipses. 

For detailed information on creating EXEC procedures, see "Part 3. 
Learning to Use EXEC. " 
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Section 9. Developing DOS Programs Under CMS 



You can use CMS to create, compile, execute and debug DOS programs 
written in assembler, COBOL, or PL/I programming languages. CMS 
simulates many DOS/VS functions so that you can use the interactive 
facilities of VM/370 to develop your programs, and then execute them in 
a DOS virtual machine. 

Section 9 tells you how to use the CMS/DOS environment, and describes 
the CMS commands you can use to manipulate DOS disks and DOS files and 
CMS/DOS commands you can use to simulate the functions of the Disk 
Operating System (DOS/VS) : 

The CMS/DOS environment 

Using DOS files on DOS disks 

Using the ASSGN command 

Using the DLBL command 

Using DOS libraries in CMS/DOS 

Using macro libraries 

DOS assembler language macros supported 

Assembling source programs 

Link-editing programs in CMS/DOS 

Executing programs in CMS/DOS 

For a practice terminal session using the commands and technigues 
presented in this section, see "Appendix D: Sample Terminal Sessions." 

h U2E3 ILliS-Mi ISE5iJ32lo3y 

CMS/DOS is neither CMS nor is it DOS; it is a composite, and its 
vocabulary contains both CMS and DOS terms. CMS/DOS performs many of 
the same functions as DOS, but where, under DOS, a function is initiated 
by a control card, in CMS it is initiated by a command. Many CMS/DOS 
commands, therefore, have the same names as the DOS control statement 
that performs the same function. In those cases where the control 
statement you would use in DOS and the command you use in CMS are 
different, the differences are explained. For the most part, whenever a 
term that is familiar to you as a DOS term is used, it has the same 
meaning to CMS/DOS, unless otherwise indicated. 



The CMS/DOS Environment 

After you have loaded CMS into your virtual machine you can enter the 
CMS/DOS environment by issuing 

set dos on 

If you Want to access a DOS system residence volume during your CMS/DOS 
terminal session, you should link to and access the disk that contains 
the DOS SYSRES before you issue the SET command. For example, if you 
share the system residence volume with other users and it is in your 
directory at virtual address 390, you would issue the command 

access 390 g 

and then issue the SET command as follows: 
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set dos on g 

to indicate that the SYSBES is located on your G-disk. If you are gcing 
to use the CMS/DOS librarian facilities to access any of the libraries 
on the system residence volume, you must enter the CMS/DOS environment 
this way. 

If you are using CMS exclusively for DOS applications, you could put 
the ACCESS and SET DOS ON commands in your PROFILE EXEC. 

If you are going to use Access Method Services functions in CMS/DOS, 
or execute functions that read or write VSAM data sets, you must use the 
VSAM option of the SET DOS ON command: 

set dos on g (vsam 

When you are using CMS/DOS, you can use your virtual machine just as 
you would if you were in the CMS environment; but you cannot execute any 
CMS commands or program modules that load and/or use OS macros. The 
SCRIPT command, for example, uses OS macros, and is therefore invalid in 
the CMS/DOS environment. 

You have, however, in addition to the CP and CMS commands available, 
a series of commands that simulate DOS/VS functions. Except for the 
DLBL and DGSLIB commands, these commands or operands should only be 
issued in the CMS/DOS environment. 

The CMS/DOS commands are summarized in Figure 15. 

Using DOS Files on DOS Disks 

You can have DOS disks attached to your virtual machine by a directory 
entry or you can link to a DOS disk with the LINK command. You can use 
the ACCESS command to assign a mode letter to the disk: 

access 155 b 

and the RELEASE command to release it: 

release b 

Except for VSAM disks, you cannot write on DOS disks, or update DOS 
files on them. You can, however, execute programs and CMS/DOS commands 
that read from these files, and you can use the LISTDS command to 
display the file-ids of files on a DOS disk, for example: 

listds b 

You can also verify the existence of a particular file. For example, if 
the file-id is NEW. TEST. DATA you can enter 

listds new test data b 

You can use this form only if the file-id has 1- to 8-character 
qualifiers separated by blanks. If the file-id of the DOS file you want 
to verify contains embedded blanks, for example NEW. TEST DATA, then you 
have to enter the LISTDS commands with a question mark: 

listds ? b 

CMS responds 

ENTER DATA SET NAME: 
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Command 
ASSGN 

DLBL 

DOSLIB 

DOSLKED 

DSERV 

DOSPLI 

ESERV 

FCOBOL 
FETCH 

GLOBAL 

LISTIO 

OPTION 
QUERY 



PSERV 



RSERV 



SET 



SSERV 



Figure 15, 



Function 



Relates system and programmer logical units to physical 
devices. 

Relates a program ddname (filename) to a real disk file 
so you can perform input/output operations on it. 

Lists or deletes phases from a CMS/DOS phase library, or 
compresses the library. 

Link-edits CMS TEXT files or DOS phases from system or 
private relocatable libraries. 

Displays the directories of DOS libraries. 

An EXEC procedure that invokes the DOS/VS PL/I compiler. 

An EXEC procedure that invokes the ESERV utility functions 
on edited assembler language macros. 

An EXEC procedure that invokes the DOS/VS COBOL compiler. 

Loads executable phases from a DOSLIB or DOS library into 
storage for execution, and optionally starts execution. 

When you want DOSLIBs searched for executable phases or 
macro libraries searched for macro definitions, you must 
identify them with the GLOBAL command. 

Displays the current assignments of system and programmer 
logical units, and optionally creates an EXEC file to 
contain the information. 

Sets or changes the options in effect for the DOS/VS 
COBOL compiler. 

Use QUERY command operands to list current DLBL defintions 
(QUERY DLBL) , to determine whether or not you are in 
the CMS/DOS environment (QUERY DOS) , the setting of the 
UPSI byte (QUERY UPSI) , the DOSLIBs identified by GLOBAL 
commands (QUERY DOSLIB or QUERY LIBRARY) , which options 
are in effect for the COBOL compiler (QUERY OPTION) , or to 
find out whether you have set a virtual partition size 
(QUERY DOSPART) . 

Creates CMS files with a filetype of PROC from the DOS/VS 
procedure library, or displays, prints or punches 
procedures. 

Copies a relocatable module from a DOS library and places 
it in a CMS file with a filetype of TEXT, or displays, 
prints, or punches modules. 

The SET command has operands that allow you to enter or 
leave the CMS/DOS environment (SET DOS ON or SET DOS OFF) , 
to set the UPSI byte (SET UPSI) , and to set a virtual 
partition size (SET DOSPART) . 

Creates CMS COPY files from books on DOS source statement 
libraries . 



CMS/DOS Commands and CMS Commands with Special Operands for 
CMS/DOS 
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and you can enter the exact file-id: 

new. test data 

If the data set exists, you receive a response 

FM DATA SET NAME 
B NEW. TEST DATA 



READING DOS FILES 

Under CMS/DOS, you can execute programs that read DOS sequential (SAM) 
files; you can also execute programs that read and write VSAM files. 
You cannot, however, execute programs to read direct (DAM) or indexed 
sequential (ISAM) DOS files. 

Complete information on using CMS to access and manipulate VSAM files 
is described in "Section 10. Using Access Method Services and VSAM In 
CMS and CMS/DOS." The discussion below lists the restrictions placed on 
reading SAM files. 



I^strictions on Reading DOS Disk Files in CMS 

CMS cannot read DOS files that; 

• Have the input security indicator on. 

• Contain more than 16 user label and/or data extents. (If the file 
has user labels, they occupy the first extent; therefore the file 
must contain no more than 15 data extents.) 

• Multivolume files are read as single-volume files. End-of -volume is 
treated as end-of-file. There is no end-of-volume switching. 

• User labels in user-labeled files are bypassed. 

CMS does not support duplicate volume labels; you cannot access more 
than one volume with the same 6-character label while you are using 
CMS/DOS. 



CREATING CMS FILES FROM DOS LIBRARIES 

You can create CMS files from existing DOS files on DOS disks. CMS 
simulates the DOS librarian functions DSERV, RSERV, SSERV, ESERV, and 
PSERV with commands of the same names; you can use these CMS/DOS 
commands to create CMS files from relocatable, source statement, or 
procedure libraries located either on the DOS system residence volume or 
in private libraries. The functions are fully described later in this 
section. 
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CoEiincj DOS Disk and Ta^e Data Files 

If you want to create CMS files from DOS files that are not cataloged in 
libraries, or from DOS files on tape, you can use the MOVEFILE command. 
The MOVEFILE command allows you to copy a file from one device to 
another device of the same or a different type. Before issuing the 
MOVEFILE command, the input and the output files must be described to 
CMS with the FILEDEF command. 

The MOVEFILE and FILEDEF commands are described and examples are 

given of how to use them in "Section 8. Developing OS Program Under 

CMS." The procedures are the same for copying DOS files as for OS data 

sets. You must however, keep the following in mind: 

• Since DOS files on DOS disks do not contain BLKSIZE, RECFM, or LHECL 
options, these options must be specified via the FILEDEF command; 
otherwise, defaults of BLOCKSIZE=32760 and RECFM=U are assigned. 
LEECL is not used for RECFM=U files. 

• If a DOS file- id does not follow OS naming conventions (that is, 1- 
to 8-byte gualifiers with each qualifier separated by a period; up to 
U4 characters including periods) , you must use the DSN ? operand of 
FILEDEF and the ? operand of LISTDS to enter the DOS file-id. 



R§H<ii!12 iB J§§i Card Decks 

If you have DOS files or source programs on cards, you can create CMS 
files directly by having these cards read into the real system card 
reader. You direct the cards to your virtual machine by punching a CP 
ID card in this format: 

ID HARMONY 

and placing this card in front of your card deck. When the cards appear 
in your virtual card reader, you can read them onto your CMS A-disk with 
the READCARD command: 

readcard dataproc assemble 

You can use the editor to remove any DOS control cards that may be 
included in the deck. 



Using Tap.es in CMS^DOS 

CMS/DOS does not process tape labels. In general, CMS/DOS either 
bypasses labels on input tapes or passes control to a user routine to 
process header labels on input tapes. CMS/DOS processes all output 
tapes as tapes with no labels. Trailer labels are not supported for 
input tapes or output tapes. 

CMS/DOS passes control to user label routines, if there are any, for 
input tapes with standard or nonstandard labels. 

If a tape which is opened as an output tape already has a header 
label (standard or nonstandard) , CMS/DOS writes over that label when it 
writes data to the tape. 
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There is no equivalent in CMS/DOS to the DOS/VS TLBL control 
statement. The TLBL label function is not required in CMS/DOS. 



Using the ASSGN Command 

The ASSGN and DLBL commands perform the same functions for CMS/DOS as 
the ASSGN and DLBL control statements in DOS/VS. You use the ASSGN 
command to desiqnate an I/O device for a system or programmer logical 
unit (SYSxxx) and, if the device is a disk device, you can use the DLBL 
command to establish a real file identification for a symbolic filename 
in a program. The DLBL command is described under "Using the DLBL 
Command. " 

In addition to using the ASSGN command to relate real I/O devices 
with symbolic units, you must use it in CMS/DOS to: 

• Assign SYSIN or SYSIPT for the input source file for a language 
compiler when you use the DOSPLI or FCOBOL commands. 

• Identify the disk, by mode letter, on which a private core image, 
relocatable, or source statement library resides. 

• Assign SYSIN or SYSIPT to the CMS disk on which an ESERV file, 
containing control statements for the ESERV program, resides. 

When you enter the ASSGN command, you must supply the logical unit 
and the device, for example 

assgn syslOO printer 

assigns the logical unit SYS100 to the printer. When you want to make 
an assignment to a disk device, you must specify the mode letter at 
which the disk is accessed. The command 

assgn sys010 b 

assigns the logical unit SYS010 to your B-disk. 

The system logical units you can assign and the valid device types 
you can assign to them in CMS/DOS follow. 

SYSIPT, SYSRDR, SYSIN: These units can be assigned to disk (mode), TAPE, 
or READER. If you" make an assignment to SYSIN, both SYSRDR and SYSIPT 
are also assigned the same device. 

SYSLST: The system logical unit for listings can be assigned to disk 
(mode) , PRINTER, or TAPE. 

SYSLOG: Terminal or operator output or messages can be assigned to 

PRINTER or TERMINAL. CMS/DOS always assigns SYSLOG to TERMINAL by 

default, so you never have to make this assignment except when you want 

to alter it. 

SYSPCH: Punched output, for example text decks, can be assigned to 
PUNCH, disk (mode), or TAPE. 

S.ISCLB, SYSRLB, SYSSLB: The system logical units SYSCLB, SYSRLB, and 
SYSSLB can be assigned to private core image, relocatable, and source 
statement libraries, respectively. The only valid assignments for these 
units is to disk (mode) . If you want to reference private libraries 
with the DSERV, ESERV, FETCH, SSERV, or RSERV commands, you must assign 
SYSCLB, SYSRLB, or SYSSLB to the disks on which the libraries reside. 
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P£03£§H§£ Logical Hfiit§ 

You can assign programmer logical units SYS000 through SYS241 with the 
ASSGN command. This deviates from DOS/VS, where the number of 
programmer logical units varies according to the number of partitions. 



MANIPULATING DEVICE ASSIGNMENTS 

Besides assigning I/O devices, the ASSGN command can also negate a 
previous assignment: 

assgn syspch ua 

or specify that, for a given device, no real I/O operation is to be 
performed during the execution of a program: 

assgn sys009 ign 

When you release a disk from your virtual machine, any assignments made 
to that disk are unassigned. 

You can find out the current assignments for system and programmer 
logical units with the LISTIO command, which lists all the system or 
programmer logical units, even those that are unassigned: 

listio 

To list only currently assigned units, enter 

listio a 

To find out the current assignment of one specific unit, for example 
SYS100, enter 

listio syslOO 

With the EXEC option of the LISTIO command, you can create a disk 

file containing the list of assignments. The $LISTIO EXEC that is 

created contains two EXEC numeric variables, 61 and S2, for each unit 
listed. For example, if you entered the command 

listio sys081 (exec 

then the file $LISTIO EXEC may contain the record 

&1 &2 SYS081 PRINTER 

When you use the STAT option, LISTIO lists, for disk devices, whether 
the disk is read-only or read/write, for example 

listio syslOO 
SYS100 B R/W 

indicates that SYS100 is assigned to the B-disk, which is a read/write 
disk. 

You can cancel all current assignments by leaving the CMS/DOS 
environment and then re-entering it: 

set dos off 
set dos on 
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VIRTUAL MACHINE ASSIGNMENTS 

When you assign a physical device type to a system or programmer logical 
unit, CMS relates the device to your virtual machine configuration; you 
receive an error message if you try to assign a logical unit to a device 
not in your configuration. For example, if you are using the ASSGN 
command to assign a logical unit to a disk file, you must specify the 
access mode letter of the disk. If the disk is not accessed, the ASSGN 
command fails. 

For another example, if you issue 

assgn syspch punch 

the punch specified is your own virtual machine card punch. The actual 
destination of punched output then depends on the spooling 
characteristics of the punch; if it is spooled to another user or to *, 
then no real cards are punched, but virtual card images are placed in 
the virtual reader of the destination userid, which may be another 
virtual machine or your own. 

CMS supports only one reader, one punch, and one printer; you cannot 
make any assignments for multiple output devices in CMS/DOS. When you 
make an assignment for a logical unit that has already been assigned, it 
replaces the current assignment. 



Using the DLBL Command 

Use the DLBL command to supply CMS/DOS with specific file identification 
information for a disk file that is going to be used for input or 
output. For any DLBL command you issue, you must previously have issued 
an ASSGN command for the disk, specifying a system or programmer logical 
unit. The basic relationship is: 

assgn SYSxxx mode 

dlbl filename mode DSN ? (SYSxxx 

Both the SYSxxx and the mode values must match on the ASSGN and DLBL 
commands; the disk on which the file resides must be accessed at mode. 

The filename on the DLBL command line, called a ddname in CMS/DOS, 
corresponds to the symbolic name for a file in a program. If you want to 
reference a private DOS library, you must use one of the following 
ddnames: 

System 

t23ical Unit Fil§U§J!!e 

SYSCLB IJSYSCL 

SYSRLB IJSYSRL 

SYSSLB IJSYSSL 



ENTERING FILE IDENTIFICATIONS 

When you issue the DLBL command you must identify the file, by file-id 
(for a DOS file) or by file identifier (for a CMS file) . The keywords 
DSN and CMS indicate whether it is a DOS file or a CMS file, 
respectively. 
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If the file is a DOS file residing on a DOS disk, you can enter the 
DLBL command in one of two ways. For example, for a file named 
TEST. INPUT you could enter either: 

assgn sys101 d 

dlbl infile d dsn test input (sys101 

— or — 

assgn sys101 d 
dlbl infile d dsn ? (sys101 
ENTER DATA SET NAME: 
test. input 

For any DOS file with a file-id that contains embedded blanks or 
hyphens, you must use the "DSN ?" form. 

When you issue a DLBL command for a CMS file, you enter the filename 
and filetype following the keyword CMS: 

assgn sys102 a 

dlbl outfile a cms new output (sys102 

In this example, if SYS 102 is defined as an output file for a program, 
the output is written to your CMS A-disk in a file named NEW OUTPOT. 

You can, for convenience, use a CMS default file identifier. If you 
enter 

dlbl outfile a cms (sys102 

then the output filetype defaults to that of the ddname and the filename 
to FILE. So, this output file is named FILE OUTFILE. 



Clearing and Dis£layinc[ File Definitions 

You can clear a DLBL definition for a file by using the CLEAR operand of 
the DLBL command: 

dlbl outfile clear 

To clear all existing definitions, except those entered with the PERM 
option, you can enter 

dlbl * clear 

This command is issued by the assembler and the language processors when 
they complete execution. Definitions entered with the PERM option must 
be individually cleared. 

Whenever you use the HX Immediate command to halt the execution of a 
program, the DLBL definitions in effect are cleared, including those 
entered with the PERM option. 

You can find out what definitions are currently in effect by issuing 
the DLBL command with no operands: 

dlbl 

or, you can use the QUERY command with the DLBL operand. 



Section 9. Developing DOS Programs Under CMS 167 



Uising DOS Libraries in CMS/DOS 

CMS/DOS provides you with the capability of using various types of files 
from DOS system or private libraries. You can copy, punch, display at 
the terminal, or print: 

• Books from system or private source statement libraries using the 
SSERV command. 

• Relocatable modules from system or private relocatable libraries 
using the RSERV command. 

• Procedures from the system procedure library using the PSERV 
command. 

You can also: 

• Copy and de-edit macros from system and private E sublibraries using 
the ESERV command. 

• Access the directories of system or private libraries using the DSERV 
command. 

• Link-edit relocatable modules from system or private relocatable 
libraries with the DOSLKED command. 

• Read core image phases from system or private core image libraries 
into storage for execution using the FETCH command. 



THE SSERV COMMAND 

If you have cataloged source programs or copy files on the system source 
statement library and you want to use CMS to modify and test them, you 
can copy them into CMS files using the SSERV command. For example, 
suppose you want to copy a book named PROCESS from the A sublibrary on 
the system residence volume. The DOS system residence is in your 
virtual machine configuration at virtual address 350, and you have 
accessed it as your F-disk. First, to indicate to CMS/DOS that the 
system residence is on your F-disk, you enter 

set dos on f 

then you can enter the SSERV command, specifying the sublibrary 
identification and the book name: 

sserv a process 

This creates, from the A sublibrary, a file named PROCESS COPY and 

places it on your A-disk. If the book contained assembler language 

source statements you would want the filetype to be ASSEMBLE, so you may 
enter 

sserv a process assemble 

If you want to copy a book from a private source statement library, 
you must first use the ASSGM and DLBL commands to make the library known 
to CMS/DOS. For example, to obtain a copy file from a private library 
on a DOS disk accessed as your D-disk, enter: 
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assgn sysslb d 

dlbl ijsyssl d dsn ? (sysslb 
ENTER DATA SET NAME: 
program. test library 

Now, when you enter the SSERV command 

sserv t setup copy 

the book named SETUP in the T sublibrary of PROGRAM. TEST LIBRARY is 
copied into a CMS file named SETUP COPY. 



THE RSERV COMMAND 

In CMS/DOS, to manipulate relocatable modules that have been cataloged 
either on the system or a private relocatable library you must first 
copy them into CMS files with the RSERV command. You can link-edit 
modules directly from DOS relocatable libraries, but if you want to add 
or modify linkage editor control statements for a module, you must place 
the control statements in a CMS file. 

If you are copying a relocatable module from the system relocatable 
library, then you should make sure that you have indicated the system 
residence disk when you entered the CMS/DOS environment: 

set dos on f 

then you can issue the RSERV command specifying the name of the 
relocatable module you want to copy: 

rserv rtna 

The execution of this command results in the creation of a CMS file 
named RTNA TEXT on your A-disk. 

If you want to copy a relocatable module from a private relocatable 
library, you must first use the ASSGN and DLBL commands to make the 
private library known to CMS/DOS: 

assgn sysrlb d 

dlbl ijsysrl d dsn reloc lib (sysrlb 

Then, issue the RSERV command for a specific module in that library: 

rserv testrtna 

to create the CMS file TESTRTNA TEXT from the module named TESTRTNA. 



THE PSERV COMMAND 

If you want to copy DOS cataloged procedures into CMS files to use, for 
example, in preparing job streams for a DOS/VS virtual machine, you can 
use the PSERV command: 

pserv prepjob 

This command creates a CMS file on your A-disk; the file is named 
PREPJOB PROC. To copy a procedure from the procedure library you must 
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have entered the CMS/DOS environment specifying a disk mode for the 
system residence volume. 

You cannot execute DOS/VS procedures directly from the CMS/DOS 
environment. However, if you modify a procedure, you can punch it to a 
virtual machine that is running a DOS/VS system, and execute it there. 



THE ESERV COMMAND 

The CMS/DOS ESERV command is actually an EXEC procedure that calls the 
DOS/VS ESERV utility program. To use the ESERV program, you first must 
use the CMS Editor to create a file with a filetype of ESERV that 
contains the ESERV control statements you want to execute. For example, 
if you want to write a de-edited copy of the macro DTFCD onto your 
A-disk, you might create a file named DTFCD ESERV, with the record: 

PUNCH E. DTFCD 

As when you submit ESERV jobs in DOS/VS, column 1 must be blank. 

Then, you must assign SYSIN to the device on which the ESERV source 
file resides, usually your A-disk: 

assgn sysin a 

Then you can enter the ESERV command specifying the filename of the 
ESERV file: 

eserv dtfcd 

No other ASSGN commands are required; the CMS/DOS ESERV EXEC makes 
default assignments for SYSPCH and SYSLST to disk. 

To copy and de-edit macros from a private E sublibrary, you must 
first issue the ASSGN and DLBL commands to identify the library, for 
example 

assgn sysslb c 

dlbl ijsyssl c dsn test macros (sysslb 

The SYSLST output is contained in a CMS file with the same filename 
as the ESERV file and a filetype of LISTING; you must examine the 
LISTING file to see if the ESERV program executed successfully. You can 
either edit it (using the CMS Editor) , or display its contents with the 
TYPE command : 

type dtfcd listing 

The SYSPCH output is contained in a file with the same name as the 
ESERV file and a filetype of MACRO. If you want to punch ESERV output 
to your virtual card punch, make an assignment of SYSPCH to PUNCH. 

When you use the PUNCH or DSPCH ESERV control statements, CATAL.S, 
END, or /* records may be inserted in the output file. When you use the 
MACLIB command to add the MACRO file to a CMS macro library, these 
statements are ignored. 

See "Using Macro Libraries" for information on creating and 
manipulating CMS macro libraries. 
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THE DSERV COMMAND 

You can use the DSERV command to examine the contents of system or 
private libraries. If you do not specify any options with it, the DSERV 
command creates a disk file* named DSERV MAP, on your A-disk. You can 
use the PRINT or TERM options to specify that the directory list is 
either to be printed on your spooled printer or displayed at your 
terminal. You can also use the SORT option to create a list in 
collating sequence. 

In order to examine a system directory, you must have entered the 
CMS/DOS environment specifying the mode letter of the DOS system 
residence: 

set dos on f 

If you want to examine the directory of a private source statement, 
core image, or relocatable library you must issue the ASSGN and DLBL 
commands establishing SYSSLB, SYSCLB, or SYSRLB, before using the DSERV 
command. 

For example, to display at your terminal an alphameric list of 
procedures cataloged on the system procedure library, you would issue 

dserv pd (sort term 

If the directory you are examining is for a core image library, you 
can specify a particular phase name to ascertain the existence cf the 
p h as e : 

dserv cd phase $$bopen (term 

To list the directory of a private source statement library, you 
would first issue the ASSGN and ELBL commands: 

assgn sysslb b 

dlbl ijsyssl b dsn test source (sysslb 

then enter the DSERV command 

dserv sd 

The CMS file, DSERV MAP A, that is created in this example contains the 
directory of the private source statement library TEST. SOURCE. 



USING DOS CORE IMAGE LIBRARIES 

You can load core image phases from DOS core image libraries into 
virtual storage and execute them under CMS/DOS. Since CMS cannot write 
directly to DOS disks, linkage editor output under CMS/DOS is placed in 
a special CMS file called a DOSLIB. When you execute the FETCH command 
in CMS/DOS you can load phases from either system or private DOS core 
image libraries as well as from CMS DOSLIBs. More information on using 
the FETCH command is contained under "Executing Programs in CMS/DOS." 
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Using Macro Libraries 

DOS/VS macro libraries cannot be accessed directly by the VM/370 
assembler. If you want to assemble DOS programs in CMS/DOS that use DOS 
macro or copy files that are on the system or a private macro library 
you must first create a CMS macro library (MACLIB) containing the macros 
you wish to use. Since the process of creating a CMS MACLIB from the 
DOS system source statement library (E sublibrary) can be very 
time-consuming, you should check with your installations system 
programmer to see if it has already been done, and to verify the 
filename of the macro library, so that you can use it in CMS/DOS. 

Note: The DOS/VS PL/I and DOS/VS COBOL compilers executing in CMS/DOS 
cannot read macro or copy files from CMS MACLIBs. 

If you want to extract DOS system macros to modify them for your 
private use, or if you want to use macros from a private library in CMS, 
you must use the procedure outlined below to create the MACLIB files. 

CMS MACLIBS 

A CMS macro library has a filetype of MACLIB. You can create a MACLIB 
from files with filetypes of MACRO or COPY. A MACBO file may contain 
macro definitions; COPY files contain predefined source statements. 

When you want to assemble a source program that uses macro or copy 
definitions, you must ensure that .the library containing the code is 
identified before you invoke the assembler. Otherwise, the library is 
not searched. You identify libraries to be searched using the GLOBAL 
command. For example, if you have two MACLIBs that contain your private 
macros and copy files whose names are TESTMAC MACLIB and TESTCOPY 
MACLIB, you would issue the command 

global maclib testmac testcopy 

The libraries you specify on a GLOBAL command line are searched in the 

order you specify them. A GLOBAL command remains in effect for the 

remainder of your terminal session, or until you IPL CMS. To find out 

what macro libraries are currently available for searching, issue the 
command 

query maclib 

You can reset the libraries or the search order by reissuing the GLOBAL 
command. 



CREATING A CMS MACLIB 

To create a CMS macro library, each macro or copy file you want included 
in the MACLIB must first be contained in a CMS file with a filetype of 
COPY or MACRO. If you are creating a CMS MACLIB file from a DOS library 
you must use the SSERV command to copy a file from any source statement 
library other than an E sublibrary, or use the ESERV command to copy and 
de-edit a macro from an E sublibrary. The SSERV command uses a default 
filetype of COPY; the ESERV command uses a default filetype of MACRO. 

The following example shows how to copy macros from various sources 
and shows how to create and use the CMS MACLIB that contains these 
macros. 
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1 . Enter the CMS/DOS environment with the DOS system residence on a 
disk accessed as mode C: 

set dos on c 

2. Copy the macro book named OPEN from the A sublibrary of the system 
source statement library: 

sserv a open 

3. Establish a private source statement library: 

access 351 d 

assgn sysslb d 

dlbl ijsyssl d dsn ? (sysslb 

test source. lib 

4. Issue the SSERV command for a macro in the M sublibrary of TEST 
SOURCE. LIB: 

sserv m releas 

5. Create an ESERV file to copy from the E sublibrary: 

edit contrl eserv 

NEW FILE 

EDIT: 

input punch contrl 

file 

6. Execute the ESERV command: 

assgn sysin a 
eserv contrl 

7. Create a CMS macro library named MYDOSMAC from the files just 
created, which are named OPEN COPY, RELEAS COPY, and CONTRL MACRO: 

maclib gen mydosmac open releas contrl 

8. To use these macros in an assembler language program, you must 
indicate that this MACLIB is accessible before assembling a source 
file: 

global maclib mydosmac 
THE MACLIB COMMAND 

The MACLIB command performs a variety of functions. You use it to: 

• Create the MACLIB (GEN function) 

• Add, delete, or replace members (ADD, DEL, and REP functions) 

• Compress the MACLIB (COMP function) 

• List the contents of the MACLIB (MAP function) 

Descriptions of these MACLIB command functions follow. 

GEN Function: The GEN (generate) function creates a CMS macro library 
from input files specified on the command line. The input files must 
have filetypes of either MACRO or COPY. For example: 

maclib gen mymac get pdump put regegu 
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creates a macro library with the file identifier MYMAC MACLIB A1 from 
macros existing in the files with the file identifiers: 



GET 



/MACRO), PDUMP /MACRO\,PUT J MACRO), and REGEQU (MACRO) 
(COPY / { COPY j \COPY J \COPY J 



If a file named MYMAC MACLIB A1 already exists, it is erased. 

Assume that the files GET MACRO, PDUMP COPY, PUT MACRO, and REGEQU 
COPY exist and contain macros in the following form: 

GET MACRO PDUMP COPY PUT MACRO REGEQU COPY 



GET *COPY PDUMP PUT XREG 

PDUMP 
WAIT *COPY WAIT YREG 

WAIT 

The resulting file, MYMAC MACLIB A1, contains the members: 



GET 


WAIT 


WAIT 


PUT 


PDUMP 


REGEQU 



The WAIT macro, which appears twice in the input to the command, also 
appears twice in the output. The MACLIB command does not check for 
duplicate macro names. If, at a later time, the WAIT macro is requested 
from MYMAC MACLIB, the first WAIT macro encountered in the directory is 
used . 

When COPY files are added to MACLIBs, the name of the library member 
is taken from the name of the COPY file, or from the *COPY statement, as 
in the file PDUMP COPY, above. Note that although the file REGEQU COPY 
contained two macros, they were both included in the MACLIB with the 
name REGEQU. When the input file is a MACRO file, the member name is 
taken from the macro prototype statement in the MACRO file. 

ADD Function: The ADD function appends new members to an existing macro 
library. For example, if MYMAC MACLIB A1 exists as created in the 
example in the explanation of the GEN function and the file DTFDI COPY 
exists as follows: 

♦COPY DTFDI 

DTFDI macro definition 
*COPY DIMOD 

DIMOD macro definition 

if you issue the command 

maclib add mymac dtfdi 
the resulting MYMAC MACLIB A1 contains the members: 



GET 


PUT 


WAIT 


REGEQU 


PDUMP 


DTFDI 


WAIT 


DIMOD 



ME Function: The REP (replace) function deletes the directory entry for 
the macro definition in the files specified. It then appends new macro 
definitions to the macro library and creates new directory entries. For 
example, assume that a macro library TESTMAC MACLIB contains the members 
A ir B, and C, and that the following command is entered: 

maclib rep testmac a c 
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The files represented by file identifiers A MACRO and C MACRO each have 
one macro definition. After execution of the command, TESTMAC MACLIB 
contains members with the same names as before, but the contents of A 
and C are different. 

DEL Function: The DEL (delete) function removes the specified macro name 
from the macro library directory and compresses the directory so there 
are no unused entries. The macro definition still occupies space in t,he 
library, but since no directory entry exists, it cannot be accessed or 
retrieved. If you attempt to delete a macro for which two macro 
definitions exist in the macro library, only the first one encountered 
is deleted. For example: 

maclib del mymac get put wait dtfdi 

deletes macro names GET, PUT, WAIT, and DTFDI from the directory of the 

macro library named MYMAC MACLIE. Assume that MYMAC exists as in the ADD 

function example. After the above command, MYMAC MACLIB contains the 
following members: 

PDUMP 
WAIT 
REGEQU 
DIMOD 

COMP Function: Execution of a MACLIB command with the DEL or REP 
functions can leave unused space within a macro library. The COMP 
(compress) function removes any macros that do not have directory 
entries. This function uses a temporary file named MACLIB CMSUT1. For 
example, the command: 

maclib comp mymac 

compresses the library MYMAC MACLIB. 

UkR Function: The MAP function creates a list containing the name of 
each macro in the directory, the size of the macro, and its position 
within the macro library. If you want to display a list of the members 
of a MACLIB at the terminal, enter the command 

maclib map mymac (term 

The default option, DISK, creates a file on your A-disk which has a 
filetype of MAP and a filename egual to the filename of the MACLIB. If 
you specify the PRINT option, then a copy of the map file is spooled to 
your virtual printer as well as being written onto disk. 



MaiEHliLiiaa MACLIB Members 

The following CMS commands supply a MEMBER option, which allows you to 
reference individual members of a MACLIB: 

• PRINT (to print a member) 

• PUNCH (to punch a member) 

• TYPE (to display a member) 

• FILEDEF (to establish a file definition for a member) 

You can use the CMS Editor to create the MACRO and COPY files and 
then use the MACLIB command to place them in a library. Once they are 
in a library, you can erase the original files. 



Section 9. Developing DOS Programs Under CMS 175 



To extract a member from a macro library, you can use either the 
PUNCH or the MOVEFILE command. If you use the PUNCH command you can 
spool your virtual card punch to your own virtual reader: 

cp spool punch to * 
then punch the member: 

punch testmac maclib (member get noheader 
and read it back onto disk: 

readcard get macro 

In the above example, the member was punched with the NOHEADER option of 
the PUNCH command, so that a name could be assigned on the READCARD 
command line. If a header had been created for the file, it would have 
indicated the filename and filetype as GET MEMBER. 

If you use the MOVEFILE command, you must issue a file definition for 
the input member name and the output macro or copy file before entering 
the MOVEFILE command: 

filedef inmove disk testcopy maclib (member enter 

filedef outmove disk enter copy a 

movefile 

This example copies the member ENTER from the macro library TESTCOPY 
MACLIB A into a CMS file named ENTER COPY. 

When you use the PUNCH or MOVEFILE commands to extract members from 
CMS MACLIBs, each member is followed by a // record, which is a MACLIB 
delimiter. You can edit the file and use the DELETE subcommand to 
delete the // record. 



§!Z§.t em MACLIBs 

The macro libraries that are on the system disk contain CMS, DOS, and OS 
assembler language macros. The MACLIBs are: 

• CMSLIB MACLIB contains the CMS macros. 

• DOSMACRO MACLIB contains DOS/VS macros that CMS/DOS routines use. 

• OSMACRO MACLIB, 0SMACR01 MACLIB, and TSOMAC MACLIB are used by OS 
programmers. 



DOS Assembler Language Macros Supported 

Figure 16 lists the DOS/VS Assembler Language macros supported by 
CMS/DOS. You can assemble source programs that contain these macros 
under CMS/DOS, provided that you have the macros available in either 
your own or a shared CMS macro library. The macros whose functions are 
described in the "Function" column with the term "no-op" are supported 
for assembly only; when you execute programs that contain these macros, 
the DOS/VS functions are not performed. To accomplish the macro 
function you must execute the program in a DOS/VS virtual machine. 
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| Macro 


svc 


Function 


I CALL 


- 


Pass control to another program 


| CANCEL 


06 


Terminate processing 


| CDLOAD 


65 


Load a VSAM phase 


| CHECK 


— 


Verify completion of a read or write operation 


| CLOSE/ 


- 


Deactivate a data file 


| CLOSER 


— 




| CNTRL 


— 


Control a physical device 


| COMRG 


33 


Return address of background partition 




- 


communication region 


| DEQ 


42 


no-op 


I DEQB 


9 


Release a resource 


| DTFxx 1 


- 


Establish file definitions 


| DUMP 


- 


Dump storage and registers and terminate processing 


1 ENQ 


41 


no-op 


| ENQB 


2 


Protect a resource 


| EOJ 


14 


Terminate processing normally 


| ERET 


— 


Provide an error routine 


| EXCP 


00 


Execute a channel program 


| EXIT PC 


17 


Return from program check routine 


| FCEPGOUT 


86 


no— op 


| FETCH 


01 


Load and pass control to a phase 




02 


Load and pass control to a logical transient 


| FREEVIS 


62 


Release user free storage 


| GENL 


— 


Generate a phase directory list 


| GET 


— 


Access a seguential file 


| GETVIS 


61 


Obtain user free storage 


| GETIME 


34 


Get the time of day 


| JDUMP 


- 


Dump storage and registers and terminate processing 


| LOAD 


04 


Read a phase into storage 


| MVCOM 


05 


Modify bytes in the partition communication region 


| NOTE 


— 


Manage data set access 


| OPEN/ 


— 


Activate a data file 


| OPENR 


— 




| PAGEIN 


87 


no— op 


| PDUMP 


- 


Dump storage and registers and continue processing 


| PFIX 


67 


no— op 


| PFREE 


68 


no-op 


| POINTR 


— 


Position a file for reading 


| POINTS 


— 


Reposition a file to its beginning 


| POINTW 


— 


Position a file for writing 


| POST 


40 


post the Event Control Block 


| PRTOV 


— 


Control printer overflow 


| POT 


— 


Write to a seguential file 


| PUTR 


— 


Communicate with the system operator 


| READ 


— 


Access a seguential file 


| RELEASE 


64 


Release a system resource 


| RELPAG 


85 


no-op 


| RELSE 


— 


Skip to begin reading next block 


| RETURN 


— 


Return control to calling program 


| RUNMODE 


66 


Check if program is running real or virtual 


| SECTVAL 


75 


Obtain a sector number 


| SEIZE 


22 


no— op 


| SETIME 


10/24 


no-op 


| SETPFA 


71 


no-op 


| STXIT AB 


37 


Provide or terminate linkage to abnormal ending 


| PC 


16 


routine 


| IT 


20 


no-op 


| OC 


18 


no-op 


| *The DOS 


declarative macros supported are: 


| DTFCN, 


DTFCD, 


DTFPR, DTFDI, DTFMT, DTFSD, DTFCP, and DTFSL 



Figure 16. DOS/VS Macros Supported by CMS (Part 1 of 2) 
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Macro SVC Function 

TRACK FREE 36 no-op 

TRACK HOLD 35 no-op 

TRUNC - Skip to begin writing next block 

TTIMER 52 Return a in Register (effectively a noop) 

USE 63 Reserve a system resource 

WAIT 07 Wait for the completion of I/O 

WRITE - Write to a sequential file 

xxMOD 1 - Create Logical IOCS routine inline 



*The DOS logic modules supported are: 

CDMOD, PRMOD, DIMOD, MTMOD, SDMODxx, and CPMOD 



Figure 16. DOS/VS Macros Supported by CMS (Part 2 of 2) 



Assembling Source Programs 

If you are a DOS/VS Assembler Language programmer using CMS/DOS, you 
should be aware that the assembler used is the VM/370 assembler, not the 
DOS/VS assembler. The major difference is that the VM/370 assembler, 
invoked by the ASSEMBLE command, is designed for interactive use, so 
that when you assemble a program, error messages are displayed at your 
terminal when compilation is completed, and you do not have to wait for 
a printed listing to see the results. You can correct your source file 
and reassemble it immediately. When your program assembles without 
errors, you can print your listing. 

To specify options to be used during the assembly, you enter them on 
the ASSEMBLE command line. So, for example, if you do not want the 
output LISTING file placed on disk, you can direct it to the printer: 

assemble myfile (print 

All of the ASSEMBLE command options are listed in VMZ3_70: CMS Command 
and Macro Reference. 

When you invoke the ASSEMBLE command specifying a file with a 
filetype of ASSEMBLE, CMS searches all of your accessed disks, using the 
standard search order, until it locates the file. When the assembler 
creates the output LISTING and TEXT files, it writes them onto disk 
according to the following priorities: 

1. If the source file is on a read/write disk, the TEXT and LISTING 
files are written onto the same disk. 

2. If the source file is on a read-only disk that is an extension of a 
read/write disk, the TEXT and LISTING files are written onto the 
parent disk. 

3. If the source is on any other read-only disk, the TEXT and LISTING 
files are written onto the A-disk. 

In all of the above cases, the filenames assigned to the TEXT and 
LISTING files are the same as the filename of the input file. 

The output files used by the assembler are defined via FILEDEF 
commands issued by CMS when it calls the assembler. If you issue a 
FILEDEF command using one of the assembler ddnames before you issue the 
ASSEMBLE command, you can override the default file definitions. 
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The ddname for the source input file is ASSEMBLE. If you enter 

filedef assemble reader 
assemble sample 

then the assembler reads your input file from your card reader, and 
assigns the filename SAMPLE to the output TEXT and LISTING files. You 
can use this method to assemble programs directly from DOS sequential 
files on DOS disks. 

LISTING and TEXT are the ddnames assigned to the SYSLST and and 
SYSPCH output of the assembler. You might issue file definitions to 
override these defaults as follows: 

filedef listing disk assemble listfile a 
filedef text disk assemble textfile a 
assemble source 

When these commands are executed, the output from the assembly of the 
file SOURCE ASSEMBLE is written to the disk files ASSEMBLE LISTFILE and 
ASSEMBLE TEXTFILE. 

Link-editing Programs in CMS/DOS 

When the assembler or one of the language compilers executes, the object 
module produced is written to a CMS disk in a file with a filetype of 
TEXT. The filename is always the same as that of the input source 
file. These TEXT files (sometimes referred to as decks, although they 
are not real card decks) can be used as input to the linkage editor, or 
can be the target of an INCLUDE linkage editor control statement. 

You can invoke the CMS/DOS linkage editor with the DOSLKED command, 
for example: 

doslked test testlib 

where TEST is the is the filename of either a DOSLNK or TEXT file (that 
is, a file with a filetype of either DOSLNK or TEXT), or the name of a 
relocatable module in a system or private relocatable library. TESTLIB 
indicates the name of the output file which, in CMS/DOS, is a phase 
library with a filetype of DOSLIB. 

When you issue the DOSLKED command, CMS first searches for a file 
with the specified name and a filetype of DOSLNK. If none are found, it 
searches the private relocatable library, if you have assigned one (you 
must issue an ASSGN command for SYSRLB and use the ddname IJSSYRL in a 
DLBL statement) . If the module is still not found, CMS searches all of 
your accessed disks for a file with the specified name and a filetype of 
TEXT. Last, CMS searches the system relocatable library, if it is 
available (you must enter the CMS/DOS environment specifying the mode 
letter of the DOS/VS system residence if you want to access the system 
libraries) . 

LINKAGE EDITOR INPUT 

You can place the linkage editor control statements ACTION, PHASE, 
INCLUDE, and ENTRY in a CMS file with a filetype of DOSLNK. When you 
use the INCLUDE statement, you may specify the filename of a CMS TEXT 
file or the name of a module in a DOS relocatable library: 

INCLUDE XYZ 
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or you may use the INCLUDE control statement to indicate that the object 
code follows: 

INCLUDE 

(CMS TEXT file) 

A typical DOSLNK file, named CONTROL DOSLNK, might contain the 
following: 

ACTION BEL 
PHASE PROGMAIN,S 
INCLUDE SUBA 
PHASE PROGA,* 
INCLUDE SUBB 

When you issue the command 

doslked control 

the linkage editor searches the following for the object files SUBA and 
SUBB: 

«» A DOS private relocatable library, provided you have issued the ASSGN 
and DLBL commands to identify it: 

assgn sysrlb d 

dlbl ijsysrl d dsn ? (sysrlb 

«» Your CMS disks for files with filenames SUBA and SUBB and a filetype 
of TEXT 

» The system relocatable library located on the DOS system residence 
volume (if it is available) 

Link-editing TEXT files 

When you want to link-edit individual CMS TEXT files, you can insert 
linkage editor control statements in the file using the CBS Editor and 
then issue the DOSLKED command: 

edit rtnb text 

EDIT: 

input include rtnc 

file 

doslked rtnb mydoslib 

When the above DOSLKED command is executed, the CMS file RTNB TEXT is 
used as linkage editor input, as long as there is no file named RTNB 
DOSLNK. The ACTION statement, however, is not recognized in TEXT 
files. 

You can also link-edit relocatable modules directly from a DOS system 
or private relocatable library, provided that you have identified the 
library. If you do this, however, you cannot provide control statements 
for the linkage editor. 

If you want to link-edit a relocatable module from a DOS private 
library and you want, also, to add linkage editor control statements to 
it, you could use the following procedure: 

1. Identify the library and use the RSERV command to copy the 
relocatable module into a CMS TEXT file. In this example, the 
module RTNC is to be copied from the library OBJ. MODS: 
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assgn sysrlb e 

dlbl ijsysrl e dsn obj nods (sysrlb 

rserv rtnc 

2. Create a. DOSLNK file, insert the linkage editor control statements, 
and copy the TEXT file created in step 1 into it using the GETFILE 
subcommand. 

edit rtnc doslnk 
input action rel 
getfile rtnc text a 
file 

3. Invoke the linkage editor with the DOSLKED command. 

doslked rtnc mydoslib 

Alternatively, you could create a DOSLNK file with the following 
records: 

ACTION REL 
INCLUDE RTNC 

and link-edit the module directly from the relocatable library. If you 
do not need a copy of the module on a CMS disk, you might want to use 
this method to conserve disk space. 

When the linkage editor is reading modules, it may encounter a blank 
card at the end of a file, or a * (comment) card at the beginning of a 
file. In either case, it issues a warning message indicating an invalid 
card, but continues to complete the link-edit. 



LINKAGE EDITOR OUTPUT: CMS DOSLIBS 

The CMS/DOS linkage editor always places the link-edited executable 
phase in a CHS library with a filetype of DOSLIB. You should specify 
the filename of the DOSLIB when you enter the DOSLKED command: 

doslked progO templib 

where PROGO is the relocatable module you are link-editing and TEMPLIB 
is the filename of the DOSLIB. 

If you do not specify the name of a DOSLIB, the output is placed in a 
DOSLIB that has the same name as the DOSLNK or TEXT file being 
link-edited. In the above example, a CMS DOSLIB is created named 
TEMPLIB DOSLIB, or, if the file TEMPLIB DOSLIB already exists, the phase 
PROGO is added to it. 

DOSLIBs can contain relocatable and core image phases suitable for 
execution in CMS/DOS. Before you can access phases in it, you must 
identify it to CMS with the GLOBAL command: 

global doslib templib permlib 

Hhen CMS is searching for executable phases, it searches all DOSLIBs 
specified on the last GLOBAL DOSLIB command line. If you have named a 
number of DOSLIBs, or if any particular DOSLIB is very large, the time 
required for CMS to fetch and execute the phase increases. You should 
use separate DOSLIBs for executable phases, whenever possible, and then 
specify only the DOSLIBs you need on the GLOBAL command. 
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When you link-edit a module into a DOSLIB that already contains a 
phase with the same name, the directory entry is updated to point to the 
new phase. However, the space that was occupied by the old phase is not 
reclaimed. You should periodically issue the command 

doslib comp libname 

where libname is the filename of the DOSLIB, to compress the DOSLIB and 
delete unused space. 

iiLi&§3§ Editor Maps 

The DOSLKED command also produces a linkage editor map, which it writes 
into a CMS file with a filename that is that of the name specified on 
the DOSLKED command line and a filetype of MAP. The filemode is always 
A5. If you do not want a linkage editor map, use the NOMAP option on 
the ACTION statement in a DOSLNK file. 



Executing Programs in CMS/DOS 

After you have assembled or compiled a source program and link-edited 
the TEXT files, you can execute the phases in your CMS virtual machine. 
You may not, however, be able to execute all your DOS programs directly 
in CMS. There are a number of execution-time restrictions placed on your 
virtual machine by VM/370. You cannfit execute a program that uses: 

• Multitasking 

• More than one partition 

• Teleprocessing 

• ISAM macros to read or write files 

The above is only a partial list, representing those restrictions with 
which you might be concerned. For a complete list of restrictions, see 
the VM/370: Planning and System Generation Guide. 



EXECUTING DOS PHASES 

You can load executable phases into your CMS virtual machine using the 
FETCH command. Phases must be link-edited before you load them. When 
you issue the FETCH command, you specify the name of the phase to be 
loaded: 

fetch myprog 

Then you can begin executing the program by issuing the START command: 

start 

Or, you can fetch a phase and begin executing it on a single command 
line: 

fetch prog2 (start 

When you use the FETCH command without the START option, CMS- issues a 
message telling you at what virtual storage address the phase is loaded: 

PHASE PR0G2 ENTRY POINT AT LOCATION 020000 
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Location X* 20000* is the starting address of the user program area for 
CMS; relocatable phases are always loaded starting at this address 
unless you specify a different address using the ORIGIN option of the 
FETCH command: 

fetch prog3 (origin 22000 
start 

The program PR0G3 executes beginning at location 22000 in the CMS user 
program area. 



SEARCH ORDER FOR EXECUTABLE PHASES 

When you execute the FETCH command, CMS searches for the phase name you 
specify in the following places: 

1. In a DOS/VS private core image library on a DOS disk. If you have 
a private library you want searched for phases, you must identify 
it using the ASSGN and DLBL commands, using the logical unit 
SYSCLB: 

assgn sysclb d 

dlbl ijsyscl d dsn ? (sysclb 

2. In CMS DOSLIBs on CMS disks. If you want DOSLIBs searched for 
phases, you must use the GLOBAL command to identify them to 
CMS/DOS: 

global doslib templib mylib 

You can specify up to eight DOSLIBs on the GLOBAL command line. 

3. On the DOS system residence core image library. If you want the 
system core image library searched you must have entered the 
CMS/DOS environment specifying the mode letter of the system 
residence: 

set dos on z 

When you want to fetch a core image phase that has copies in both the 
core image library and a DOSLIB, and you want to fetch the copy from the 
CMS DOSLIB, you can bypass the core image library by entering the 
command 

assgn sysclb ua 

When you need to use the core image library, enter 

assgn sysclb c 

where C is the mode letter of the system residence volume. You do not 
need to reissue the DLBL command to identify the library. 



MAKING I/O DEVICE ASSIGNMENTS 

If you are executing a program that performs I/O, you can use the ASSGN 
command to relate a system or programmer logical unit to a real I/O 
device. As in DOS/VS, device type assignment in CMS/DOS is dependent on 
device specifications in the program. 
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assgn sys052 reader 
assgn syslst printer 

In this example, your program is going to read input data from your 
virtual card reader; the output print file is directed to your virtual 
printer. If you want to reassign these units to different devices, you 
must be sure that the files have been defined as device independent. 

If you assign a logical unit to a disk, you should identify the file 
by using the DLBL command. On the DLBL command, you must always relate 
the DLBL to the system or programmer logical unit previously specified 
in an ASSGN command: 

assgn sys015 b 

dlbl myfile b dsn ? (sys015 

When you enter the DLBL command with the ? operand you are prompted to 
enter the DOS file-id. 

You must issue all of the ASSGN and DLBL commands necessary for your 
program »s I/O before you issue the FETCH command to load the program 
phase and begin executing. 

SPECIFYING A VIRTUAL PARTITION SIZE 

For most of the programs that you execute in CMS, you do not need to 
specify how large a partition you want a program to execute in. When 
you issue the START command or the START option on the FETCH command, 
CMS calculates how much storage is available in your virtual machine and 
sets a partition size. 

In some instances, however, you may want to control the partition 
size, as a performance consideration (some programs may run better in 
smaller partitions) . You can set the partition size with the DOSPART 
operand of the SET command. For example, after you enter the command 

set dospart 300k 

all programs that you subseguently execute will execute in a 300K 
partition. If you enter 

set dospart off 

then CMS calculates a partition size when you execute a program. This is 
the default setting. 



SETTING THE OPSI BYTE 

If your program uses the User Program Switch Indicator (OPSI) byte, you 
can set it by using the UPSI operand of the CMS SET command. The OPSI 
byte is initially binary zeros. To set it to 1s, enter 

set upsi 11111111 

To reset it to zeros, enter 

set upsi off 

Any value you set remains in effect for the duration of your terminal 
session, unless you reload CMS (with the IPL command) . 
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DEBUGGING PROGRAMS IN CMS/DOS 

You can debug your DOS programs in CMS/DOS using the facilities of CP 
and CMS. By executing your programs interactively, you can more guickly 
determine the cause of an error or program abend, correct it, and 
attempt to execute a program again. 

The CP and CMS debugging facilities are described in "Section 11. How 
VM/370 Can Help You Debug Your Programs." Additional information for 
assembler language programmers is in "Section 13. Programming for the 
CMS Environment." 



USING EXEC PROCEDURES IN CMS/DOS 

During your program development and testing cycle, you may want to 
create EXEC procedures to contain seguences of CMS commands that you 
execute freguently. For example, if you need a number of MACLIBs, 
DOSLIBs, and DLBL definitions to execute a particular program, you might 
have an EXEC procedure as follows: 

SCONTROL ERROR TIME 

SERROR &EXIT &RETCODE 

GLOBAL MACLIB TESTLIB DOSMAC 

ASSEMBLE TESTA 

PRINT TESTA LISTING 

DOSLKED TESTA TESTLIB 

GLOBAL DOSLIB TESTLIB PROGLIE 

ACCESS 200 E 

ASSGN SYS010 E 

&BEGSTACK 

DOS. TEST3. STREAM. BETA 

&END 

DLBL DISK1 E DSN ? (SYS010 

ASSGN SYS011 PUNCH 

CP SPOOL PUNCH TO * 

ASSGN SYS012 A 

DLBL OUTFILE A CMS TEST DATA 

FETCH TESTA (START 

SIF &RETC0DE = 100 &GOTO -RET100 

SIF &RETCODE = 200 &GOTO -RET200 

SEXIT SRETCODE 

-RET100 &CONTINUE 



-RET200 &CONTINUE 



The &CONTROL and SERROR control statements in the EXEC procedure 
ensure that if an error occurs during any part of the EXEC, the 
remainder of the EXEC does not execute, and the execution summary of the 
EXEC indicates the command that caused the error. 

Note that for the DLBL command entered with the DSN ? operand, you 
must stack the response before issuing the DLBL command. In this 
example, since the DOS file-id has more than 8 characters, you must use 
the 8BEGSTACK control statement to stack it. When you use the SSTACK 
control statement, the EXEC processor truncates all words to 8 
characters. 
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When your program is finished executing, the EXEC special variable 
SRETCODE indicates the contents of general register 15 at the time your 
program exited. You can use this value to perform additional steps in 
your EXEC procedure. Additional steps are indicated in the preceding 
example by ellipses. 

For detailed information on creating EXEC procedures, see "Part 3. 
Learning To Use EXEC." 



186 IBM VM/370: CMS User's Guide 



Section 10. Using Access Method Services and VSAM Under 
CMS and CMS/DOS 



This section describes how you can use CMS to create and manipulate VSAM 
catalogs, data spaces, and files on OS and DOS disks using Access Method 
Services. The CMS support is based on DOS/VS Access Method Services and 
Virtual Storage Access Method (VSAM) ; this means that if you are an OS 
VSAM user and plan to use CMS to manipulate VSAM files you are 
restricted to those functions of Access Method Services that are 
available under DOS/VS Access Method Services. The control statements 
you can use are described in the publication DOS/VS Access Me thod 
Ser vices User_^s Guide . 

You can use CMS to 

• Execute the Access Method services utility programs for VSAM and SAM 
data sets on OS and DOS disks and minidisks. CMS can both read and 
write VSAM files using Access Method Services. 

• Compile and execute programs that read and write VSAM files from DOS 
programs written in the COBOL or PL/I programming languages. 

• Compile and execute programs that read and write VSAM files from OS 
programs written in the VS BASIC, COBOL, or PL/I programming 
languages. 

• Assemble assembler language source programs under CMS that use VSAM 
macros. You must create your own macro library from OS or DOS macro 
libraries. 

VSAM files written under CMS are wholly compatible for reading and 
writing under OS and DOS systems. None of the CMS commands normally used 
to manipulate CMS files are applicable to VSAM files, however. This 
includes such commands as PRINT, TYPE, EDIT, COPYFILE, and so on. 

This section provides information on using the CMS AMSERV command 
with which you can execute Access Method Services. The discussion is 
divided as follows: 

"Using the AMSERV command" contains general information. 

"Manipulating OS and DOS Disks for Use With AMSERV" describes how to 
use CMS commands with OS and DOS disks. 

"Defining DOS Input and Output Files" is for CMS/DOS users only. 

"Defining OS Input and Output Files" is for OS users only. 

"Using AMSERV Under CMS" includes notes and examples showing how to 
perform various Access Method Services functions in CMS. 



EXECUTING VSAM PROGRAMS UNDER CMS 

The commands that are used to define input and output data sets for 
Access Method Services, DLBL and for CMS/DOS users, ASSGN, are also used 
to identify VSAM input and output files for program execution. 
Information on executing programs under CMS that manipulate VSAM files 
is contained in the Program Product documentation for the language 
processors. These publications are listed in the VM/370: Introduction. 
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Restrictions on the use of Access Method Services and VSAM under CMS 
for OS and DOS users are listed in VM/370: CMS Command and Macro 
lefeience, which also contains complete CMS and CMS/DOS command formats, 
operand descriptions, and responses for each of the commands described 
here. 

When you are going to execute VSAM programs in CMS or CMS/DOS, you 

should remember to issue the DLBL command to identify the master 

catalog, as well as any other program input or output file you need to 
define. 



Using the AMSERV Command 

In CMS, you execute Access Method Service utility programs with the 
AMSERV command, which has the basic format 

amserv filename 

"filename" is the name of a CMS file that contains the control 
statements for Access Method Services. 

Mote: Throughout the remainder of this section the term "AMSERV" is used 
to refer to both the CMS AMSERV command and the OS/VS or DOS/VS Access 
Method Services, except where a distinction is being made between CMS 
and Access Method Services. 

You create an AMSERV file with the CMS Editor using a filetype of 
AMSERV and any filename you want, for example: 

edit mastcat amserv 

NEW FILE: 

EDIT: 

input 

The Editor recognizes the filetype of AMSERV, and so automatically sets 
the margins for your input lines at columns 2 and 72. The sample AMSERV 
file being created in the example above, MASTCAT AMSERV, might contain 
the following control statements: 

DEFINE MASTERCATALOG (NAME (MYCAT) - 
VOLUME (123U56) CYL (2) - 
FILE (IJSYSCT) ) 

Note that the syntax of the control statements must conform to the rules 
for Access Method services, including continuation characters and 
parentheses. The only difference is that the AMSERV file does not 
contain a ••/*« for a termination indicator. 

Before you can execute the DEFINE control statement in this AMSERV 
example, you must define the output file, using the ddname IJSYSCT. You 
can do this using the DLBL command. Since the exact form reguired in 
the DLBL command varies according to whether you are an OS or a DOS 
user, separate discussions of the DLBL command are provided later in 
this section. All of the following examples assume that any disk data 
set or file that you are referencing with an AMSERV command will have 
been defined by a DLBL command. 

When you execute the AMSERV command, the AMSERV control statement 
file can be on any accessed CMS disk; you do not need to specify the 
filemode, and if you are a DOS user, you do not need to assign SYSIPT. 
The task of locating the file and passing it to Access Method Services 
is performed by CMS. 
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AMSERV OUTPUT LISTINGS 

When the AMSERV command is finished processing, you receive the CMS 
Ready message, and if there was an error, the return code (from register 
15) is displayed following the "R". For example, 

R(00008) ; 

or, if you are receiving the long form of the Ready message, it appears: 

R(00008); T=0.01/0.11 10:50:23 

If you receive a Ready message with an error return code, you should 
examine the output listing from AMSERV to determine the cause cf the 
error. 

AMSERV output listings are written in CMS files with a filetype of 
LISTING; by default, the filename is the same as that of the input 
AMSERV file. For example, if you have executed 

amserv mastcat 

and the CMS Ready message indicates an error return code, you should 
examine the file MASTCAT LISTING: 

edit mastcat listing 

EDIT: 

locate /idc/#= 

Issuing the LOCATE subcommand twice to find the character string IDC 
will position you in the LISTING file at the first Access Method 
Services message. 

The publication DOS/VS Messages, Order No. GC33-5379, lists and 
explains all of the messages generated by Access Method Services 
together with the associated reason codes. 

Instead of editing the file, you could also use the TYPE command to 
display the contents of the entire file, so that you would be able to 
examine the input control statements as well as any error messages: 

type mastcat listing 

If you need to make changes to control statements before executing 
the AMSERV command again, use the CMS Editor to modify the AMSERV input 
file. 

If you execute the same AMSERV file a number of times, each execution 
results in a new LISTING file, which replaces any previous listing file 
with the same filename. 



Oat£Ut from PRINT, LISTCAT, and LISTCRA 

When you use AMSERV to print a VSAM file, or to list catalog or recovery 
area contents using the PRINT, LISTCAT, or LISTCRA control statements, 
the output is written in a listing file on a CMS read/write disk, and 
not spooled to the printer unless you use the PRINT option of the AMSERV 
command: 

amserv listcat (print 
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If you want to save the output, you should issue the AMSERV command 
without the PRINT option and then use the CMS PRINT command to print the 
LISTING file. 



CONTROLLING AMSERV COMMAND LISTINGS 

The final disposition of the listing, as a printer or disk file, depends 
on how you enter the AMSERV command. If you enter the AMSERV command 
with no options, you get a CMS file with a filetype of LISTING and a 
filename equal to that of the AMSERV input file. This LISTING file is 
usually written on your A-disk, but if your A-disk is full or not 
accessed, it is written on any other read/writ6 CMS disk you have 
accessed . 

If there is not enough room on your A-disk or any other disk, the 
AMSERV command issues an error message saying that it cannot write the 
LISTING file. If this happens, the LISTING file created may be 
incomplete and you may not be able to tell whether or not Access Method 
Services actually completed successfully. In this case, after you have 
cleared some space on a read/write disk, you may have to execute an 
AMSERV PRINT or LISTCAT function to verify the completion of the prior 
job. 

LISTING files take up considerable disk space, so you should erase 
them as soon as you no longer need them. 



AMSERV Command Listing Options 

If you do not want AMSERV to create a disk file from the listing, you 
can execute the AMSERV command with the PRINT option: 

amserv myfile (print 

The listing is spooled to your virtual printer, and no disk file is 
created. You might want to use this option if you are executing a PRINT 
or LISTCAT control statement and expect a very large output listing that 
you know cannot be contained on any of your disks. 

You can also control the filename of the output listing file by 
specifying a second name on the AMSERV command line: 

amserv listcat listcatl 

In this example, the input file is LISTCAT AMSERV and the output listing 
is placed in a file named LISTCAT1 LISTING. A subsequent execution of 
this same AMSERV file: 

amserv listcat listcat2 

creates a second listing file, LISTCAT2 LISTING, so that the listing 
created from the first execution is not erased. 
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Manipulating OS and DOS Disks for Use with AMSERV 

To use CMS VSAM and AMSERV, you can have OS or DOS disks in your virtual 
machine configuration. They can be assigned in your directory entry, or 
you can link to them using the CP LINK command. You must have read/write 
access to them in order to execute any AMSERV function or VSAM program 
that requires opening the file for output or update. 

Before you can use an OS or DOS disk you must access it with the CMS 
ACCESS command: 

access 200 d 

The response from the ACCESS command indicates that the disk is in OS or 
DOS format: 

D(200) R/H - OS 

— or — 

D(200) R/H - DOS 

You can write on these disks only through AMSERV or through the 
execution of a program writing VSAM data sets. Once an OS disk is used 
with AMSERV or VSAM, CMS considers it a DOS disk, so regardless of 
whether you are an OS user, when you access or request information about 
a VSAM disk, CMS indicates that it is a DOS disk. You can still use the 
disk in an OS or DOS system; its format is not changed. 



USIHG VM/370 MINIDISKS 

If you have a VM/370 minidisk in your virtual machine configuration, you 
can use it to contain VSAM files. Before you can use it, it must be 
formatted with the IBCDASDI program or other appropriate operating 
system utility program. When you request that a disk be added to your 
virtual machine configuration for use with VSAM files under CMS, you 
should indicate that it be formatted for use with OS or DOS. Or, you 
can format it yourself using the IBCDASDI program. A brief example of 
how to do this is given under "Using Temporary Disks," below. The 
IBCDASDI control statements are fully described in the VM/370: 
OBerator^s Guide. 

Note: If you are an OS user, you should be careful about allocating 
space for VSAM on minidisks. Once you have used CMS AMSERV to allocate 
VSAM data space on a minidisk you should not attempt to allocate 
additional space on that minidisk using an OS/VS system. OS does not 
recognize minidisks, and would attempt to format the entire disk pack 
and thus erase any data on it. To allocate additional space for VSAM, 
you should use CMS again. If you use the IBCDASDI program to format the 
disk, and use the CYLNO parameter, the entire disk is flagged as full, 
so that OS cannot allocate additional space. 



USING THE LISTDS COMMAND 

For OS or DOS disks or minidisks, you can use the LISTDS command to 
determine the extents of free space available for use by VSAM. You can 
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also determine what space is already in use. You can use this 
information to supply the extent information when you define VSAM 
files. 

The options used with VSAM disks are 

• EXTENT, to find out what extents are in use, and 

• FREE, to find out what extents are available. 

For example, if you have an OS disk accessed as a G-disk, and you enter: 

listds g (extent 

The response might look like: 

EXTENT INFORMATION FOR »VTOC» ON • G» DISK: 

SEQ TYPE CYL-HD(RELTRK) TO CYL-HD (RELTRK) TRACKS 

000 VTOC 099 00 1881 099 18 1899 19 

EXTENT INFORMATION FOR 'PRIVAT. CORE .IMAGE .LIB ■ ON 'G 1 DISK: 
SEQ TYPE CYL-HD (RELTRK) TO CYL-HD (RELTRK) TRACKS 
000 DATA 000 01 1 049 18 949 949 

EXTENT INFORMATION FOR • SYSTEM. WORK. FILE. NO. 6 ■ ON »G' DISK: 
SEQ TYPE CYL-HD (RELTRK) TO CYL-HD (RELTRK) TRACKS 
000 DATA 050 00 950 051 18 987 38 

You could also determine the extent for a particular data set: 

listds ? * (extent 

DMSLDS220R ENTER DATA SET NAME: 

system recorder file 

EXTENT INFORMATION FOR 'SYSTEM RECORDER FILE 1 ON "F* DISK: 
SEQ TYPE CYL-HD (RELTRK) TO CYL-HD (RELTRK) TRACKS 
000 DATA 102 00 1938 102 18 1956 19 
002 DATA 010 06 206 010 08 208 3 

LISTDS searches all minidisks accessed until it locates the specified 
data set. In this example, the data set occupies two separate extents on 
disk F. If the data set is a multivolume data set, extents on all 
accessed volumes are located and displayed. 

If you want to find the free extents on a particular disk, enter: 

listds g (free 

FREESPACE EXTENTS FOR •G* DISK: 

CYL-HD (RELTRK) TO CYL-HD (RELTRK) TRACKS 

052 00 988 052 01 989 2 

054 02 1028 080 00 1520 493 

081 01 1540 098 18 1880 341 

You can use this information when you allocate space for VSAM files. If 
you enter 

listds * (free 

CMS lists all the free space available on all of your accessed disks. 
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USING TEMPORARY DISKS 

When you need extra space on a temporary basis for use with CMS VSAM and 
AMSERV, you can us*e the CP DEFINE command to define a temporary minidisk 
and then use the IBCDASDI program to format it. Once formatted and 
accessed, it is available to your virtual machine for the duration of 
your terminal session or until you detach it using the CP DETACH 
command. Remember that anything placed on a temporary disk is lost, so 
that you should copy output that you want to keep onto permanent disks 
before you log off. 



Z2EJ5i§ttin.g .§ Temp_orarjf Disk 

The example below shows a control statement file and an EXEC procedure 
that, together, can be used to format a minidisk with the IBCDASDI 
program. For a complete description of the control statements used, 
refer to the VM^370: Operator's Guide. 

The input control statements for the IBCDASDI programs should be 
placed in a CMS file, so that they can be punched to your virtual card 
reader. For this example, suppose the statements are in a CMS file named 
TEMP IBCDASDI: 

DASD198 JOB 

MSG TODEV=1052,TOADDR=009 

DADEF TODEV=3330,TOADDR=198,VOLID=SCRATCH,CYLNO=10 

VLD NEWV0LID=123456 

VTOCD STRTADR=185,EXTENT=5 

END 

Now consider the CMS file named TEMPDISK EXEC: 

&ERROR &EXIT 100 

CP DEFINE T3330 198 10 

CP CLOSE C 

CP PURGE READER ALL 

ACC 190 Z/Z IPL * 

CP SPOOL PUNCH CONT TO * 

PUNCH IPL IBCDASDI Z (NOH) 

PUNCH TEMP IBCDASDI * (NOH) 

CP SPOOL PUNCH NOCONT 

CP CLOSE PUNCH 

CP IPL 00C 

You execute this procedure by entering the filename of the EXEC: 

tempdisk 

When the final line of this EXEC is executed, the IBCDASDI program is in 
control. You must then signal an Attention interrupt using the Attention 
or Enter key, and you receive the message: 

IBC105A DEFINE INPUT DEVICE 

you should enter 

input=2540,00c 

to indicate that the control statements should be read from your card 
reader, which is a virtual 2540 device at virtual address OOC. 
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When the IBCDASDI program is finished, your virtual machine is in the 
CP environment and must reload CMS (with the IPL command) to begin 
virtual machine execution. You can then access the temporary disk: 

ace 198 c 

and CMS responds 

C(198) R/W - OS 



Defining DOS Input and Output Files 

Note: This information is for DOS/VS VSAM users. OS/VS VSAM users should 
refer to the section "Defining OS Input and Output Files." 

You must use the DLBL command to define VSAM input and output files for 
both the AMSERV command and for program execution. The operands 
required on the DLBL command are: 

dlbl ddname filemode DSN datasetname (options SYSxxx 

where "ddname" corresponds to the FILE parameter in the AMSERV file and 
"datasetname" corresponds to the entry name or filename of the VSAM 
file. 

There are several options you can use when issuing the DLBL command 
to define VSAM input and output files. These are: 

• VSAM, which you must use to indicate that the file is a VSAM file. 

Note: You do not have to use the VSAM option to identify a file as a 
VSAM file if you are using any of the other options listed here, 
since they imply that the file is a VSAM file. In addition, the 
ddnames (filenames) IJSYSCT and IJSYSUC also indicate that the file 
being defined is a VSAM file. 

• EXTENT, which you must use when you are defining a catalog or a VSAM 
data space; you are prompted to enter the volume information. This 
option effectively provides the function of the EXTENT card in 
DOS/VS. 

• MOLT, which you must use in order to access a multivolume VSAM file; 
you are prompted to enter the extent information. 

• CAT, which you can use to identify a catalog which contains the entry 
for the VSAM file you are defining. 

• BUFSP, which you can use to specify the size of the buffers VSAM 
should use during program execution. 

Options are entered following the open parenthesis on the DLBL command 
line, with the SYSxxx: 

assgn sys003 e 

dlbl filel b1 dsn workfile (extent cat cat2 sys003 

Additional examples using some of these options are shown below. 
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USING VSAM CATALOGS 

While you are developing and testing your VSAM programs in CMS, you may 
find it convenient to create and use your own master catalog, which may 
be on a CMS minidisk. VSAM catalogs, like any other cluster, can be 
shared read-only among several users. 

You name the VSAM master catalog for your terminal session using the 
logical unit SYSCAT in the ASSGN command and the ddname IJSYSCT for the 
DLBL command. For example, if your VSAM master catalog is located on a 
DOS disk you have accessed as a C-disk, you would enter 

assgn syscat c 

dlbl ijsysct c dsn mastcat (syscat 

Note: When you use the ddname IJSYSCT you do not need to specify the 
VSAM option on the DLBL command. 

You must identify the master catalog at the start of every terminal 
session. If you are always using the same master catalog, you might 
include the ASSGN and DLBL commands in an EXEC procedure or in your 
PROFILE EXEC. You could also include the commands necessary to access 
the DOS system residence volume and enter the CMS/DOS environment: 

ACCESS 350 Z 

SET DOS ON Z (VSAM 

ACCESS 555 C 

ASSGN SYSCAT C 

DLBL IJSYSCT C DSN MASTCAT (SYSCAT PERM 

You should use the PERM option so that you do not have to reset the 
master catalog assignment after clearing previous DLBL definitions. 

You must use the VSAM option on the SET DOS ON command line if you 
want to use any Access Method Services function or access VSAM files. 

DefiniBS .§ Master Catalog 

The sample ASSGN and DLBL commands used in the above EXEC are almost 
identical with those you issue to define a master catalog using AMSERV. 
The only difference is that you must enter the EXTENT option so that you 
can list the data spaces that this master catalog is to control. 

As an example, suppose that you have a 30-cylinder 3330 minidisk 
assigned to you to use for testing your VSAM programs under CMS. 
Assuming that the minidisk is in your directory at address 333, you 
should first access it: 

access 333 d 
D(333) R/W - OS 

If you formatted the minidisk yourself, you know what its label is. If 
not, you can find out what the label is by using the CMS command 

guery search 

The response might be 



USR191 


191 


A 


R/W 




DOS333 


333 


C 


R/W - 


OS 


SYS190 


190 


s 


R/0 




SYS19E 


19E 


Y/S 


R/0 
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Use the label D0S333 in the VOLUMES parameter in the MASTCAT AMSERV 
file: 

DEFINE MASTERCATALOG - 
(NAME (MASTCAT ) - 
VOLUME (D0S333) - 
CYL (U) - 
FILE (IJSYSCT) ) 

Now, to find out what extents on the minidisk you can allocate for VSAM, 
use the LISTDS command with the EXTENT option: 

listds d (free 

The response from LISTDS might look like this: 

FREESPACE INFORMATION FOR 'E 1 DISK: 
CYL-HD(RELTRK) TO CYL-HD (RELTRK) TRACKS 
000 01 1 000 09 9 9 
000 11 11 029 18 569 560 

From this response, you can see that the volume table of contents (VTOC) 
is located on the first cylinder, so you can allocate cylinders 1 
through 29 for VSAM: 

assgn syscat c 

dlbl ijsysct c dsn mastcat (syscat perm extent 

DMSDLB331R ENTER EXTENT SPECIFICATIONS: 

19 551 

(null line) 

After entering the extents, in tracks, giving the relative track number 
of the first track to be allocated followed by the number of tracks, you 
must enter a null line to complete the command. A null line is reguired 
because, when you enter multiple extents, entries may be placed on more 
than one line. If you do not enter a null line, the next line you enter 
causes an error, and you must re-enter all of the extent information. 

Note that, as in DOS/VS, the extents must be on cylinder boundaries, and 
you cannot allocate cylinder 0. 

Now you can issue the AMSERV command: 

amserv mastcat 

A Ready message with no return code indicates that the master catalog is 
defined. You do not need to reissue the ASSGN and DLBL commands in order 
to use the master catalog for additional AMSERV functions. 



Defining User Catalogs 

You can use the AMSERV command to define private catalogs and spaces for 
them, also. The procedures for determining what space you can allocate 
are the same as those outlined in the example of defining a master 
catalog. 

For a user catalog, you may use any programmer logical unit, and any 
ddname: 
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access 199 e 
listds e (free 



assgn sysOOl e 

dlbl cat! e dsn private catl (sysOOl extent peri 



amserv usercat 

The file USERCAT AMSERV might contain the following: 

DEFINE OSERCATALOG - 

(NAME (PRIVATE. CAT1) - 
FILE (IJSYSUC) - 
CYL (4) - 
VOLUME (DOSVS2) - 
CATALOG (MASTCAT) ) 

After this AMSERV command has completed successfully you can use the 
catalog PRIVATE. CAT1 . When you issue a DLBL command to identify a 
cluster or data set cataloged in this catalog, you must identify the 
catalog using the CAT option on the DLBL command for the file: 

assgn syslOO c 

dlbl file2 e dsn ? (syslOO cat catl 

Or, you can define this catalog as a job catalog. 



Using a Job Catalog 

If you want to set up a user catalog as a job catalog so that it will be 
searched during all subsegUent jobs, you can define the catalog using 
the special ddname IJSYSUC. For example: 

assgn sys101 c 

dlbl ijsysuc c dsn private catl (sys101 perm 

If you defined a user catalog (IJSYSUC) for a terminal session and 
you use the AMSERV command to access a VSAM file, the user catalog takes 
precedence over the master catalog. This means that for files that 
already exist, only the user catalog is searched. When you define a 
cluster, it is cataloged in the user catalog, rather than in the master 
catalog, unless you use the CAT option to override it. 

If you want to use additional catalogs during a terminal session, you 
first define them just as you would any other VSAM file: 

assgn sys010 f 

dlbl mycat2 f dsn private cat2 (sys010 vsam 

Then, when you enter the DLBL command for the VSAM file that is 
cataloged in PRIVATE. CAT2 use the CAT option to refer to the ddname of 
the catalog: 

assgn sys011 f 

dlbl input f dsn input file (sys011 cat mycat2 
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If you want to stop using a job catalog defined as IJSYSUC, you can 
clear it using the CLEAR option of the DLBL command: 

dlbl ijsysuc clear 

Then, the master catalog becomes the job catalog for files not defined 
with the CAT option. 



Catalog Passwords 

When you define passwords for VSAM catalogs in CMS, or when you use CMS 
to access VSAM catalogs that have passwords associated with them, you 
must supply the password from your terminal when the AMSERV command 
executes. The message that you receive to prompt you for the password 
is the same message you receive when you execute Access Method Services: 

4221A ATTEMPT 1 OF 2. ENTER PASSWORD FOR JOB AMSERV FILE catalog 

When you enter the proper password, AMSERV continues execution. 



DEFINING AND ALLOCATING SPACE FOR VSAM FILES 

You can use CMS AMSERV to allocate additional data spaces for VSAM. To 
use the DEFINE SPACE control statement, you must have defined the 
catalog which that is to control the space, and you must have the volume 
or volumes on which the space is to be allocated mounted and accessed. 

For example, suppose you have a DOS-formatted 3330 disk attached to 
your virtual machine at virtual address 255. After accessing the disk 
and determining the free space on it, you could create a file named 
SPACE AMSERV: 

DEFINE SPACE - 

(FILE (FILE1) - 
TRACKS (1900) - 
VOLUME (123456) - 
CATALOG (PRIVATE. CAT2 CAT2) ) 

To execute this AMSERV file, define PRIVATE. CAT2 as a user catalog using 
the ddname CAT2, and then define the ddname for the FILE parameter: 

access 255 c 

assgn sys010 c 

dlbl cat2 c dsn private cat2 (sys010 vsam 

assgn sys011 c 

dlbl filel c (extent sys0 1 1 cat cat 2 

Note that you do not need to enter a data set name to define the space. 
When CMS prompts you for the extents of the space you can enter the 
extent specifications: 

DMSDLB331R ENTER EXTENT SPECIFICATIONS: 
190 1900 
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When you define space for VSAM, you should be sure that the VOLUMES 
parameter and the space allocation parameter (whether CYLINDER, TRACKS, 

or RECORDS) in the AMSERV file agrees with the information you provide 

in the DLBL command. All data extents must begin and end on cylinder 

boundaries. Any additional space you provide in the extent information 

that is beyond what you specified in the AMSERV file is claimed by 
VSAM. 



Specifying Multiple Extents 

When you are specifying extents for a master catalog, data space, or 
unigue file, you can specify up to 16 extents on a volume for a 
particular space. When prompted by CMS to enter the extents, you must 
separate different extents by commas, or place them on different lines. 
To specify a range of extents in the above example, you can enter 

dlbl filel c (extent sys011 
190 190, 570 190, 1900 1520 
(null line) 

— or — 

dlbl filel c (extent sys011 
190 190 
570 190 
1900 1520 

(null line) 

Again, the first number entered for each extent represents the relative 
track for the beginning of the extent and the second number indicates 
the number of tracks. 



Sjeecifjing Multivolume Extents 

You can define spaces that span up to 9 volumes for VSAM files; all of 
the volumes must be accessed and assigned when you issue the DLBL 
command to define or identify the data space. 

You should remember, though, that if you are using AMSERV and you do 
not use the PRINT option, you must have a read/write CMS disk so that 
AMSERV can write the output LISTING file. 

If you are defining a new multivolume data space cr unigue cluster, 
you must specify the extents on each volume that the data is to occupy 
(starting track and number of tracks), followed by the disk mode letter 
at which the disk is accessed and the programmer logical unit to which 
the disk is assigned: 

access 135 b 
access 136 c 
access 137 d 
assgn sys001 b 
assgn sys002 c 
assgn sys003 d 
dlbl newfile b (extent sys001 
DMSDLB331R ENTER EXTENT SPECIFICATIONS: 
100 60 b sys001, 400 80 b sys001, 60 40 d sys003 
2000 100 c sys002 
(null line) 
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If you specify more than one extent on the same line, the extents must 
be separated by commas; if you enter a comma at the end of a line, it is 
ignored. Different extents for the same volume must be entered 
consecutively. 

Note that in the preceding example, the extent information is for 
2314 disks; and that these extents are also on cylinder boundaries. 

When you enter multivolume extents you can use a default mode. For 
example: 

dlbl newfile b (extent sys001 
DMSDLB331R ENTER EXTENT SPECIFICATIONS: 
100 60, 400 80, 60 40 d sys003, 
2000 100 c sys002 
(null line) 

Any extents you enter without specifying a mode letter and SYSxxx value 
default to the mode and SYSxxx on the DLBL command line, in this case, 
the B-disk, SYS001. 

If you make any errors issuing the DLBL command or extent 
information, you must re-enter the entire command seguence. 

I5INTIFY1NG EXISTING MULTIVOLUME FILES: When you issue a DLEL command to 
identify an existing multivolume VSAM file, you must use the MOLT option 
of the DLBL command: 

dlbl old b1 dsn ? (sys002 mult 

DMSDLB220R ENTER DATA SET NAME: 

dostest. file 

DMSDLB330R ENTER VOLUME SPECIFICATIONS: 

c sys004, d sys003 

e sys007 

(null line) 

When you enter the DLBL command you should specify the mode letter and 
logical unit for the first volume on the command line. When you enter 
the MULT option you are prompted to enter additional specifications for 
the remaining extents. In the preceding example, the data set has 
extents on disks accessed as B-, C-, D-, and E-disks. 



USING TAPE INPUT AND OUTPUT 

If you are using AMSERV for a function that reguires tape input and/or 
output, you must have the tape(s) attached to your virtual machine. The 
valid addresses for tapes are 181, 182, 183, and 184. When referring to 
tapes, you can also refer to them using their CMS symbolic names TAP1 , 
TAP2, TAP3, and TAP4. 

Since CMS does not read tape labels, there is no CMS/DOS eguivalent 
to the TLBL control statement. For AMSERV functions that use tape 
input/output, you are prompted for the ddname (filename) . 

When you invoke the AMSERV command, you must use the TAPIN or TAPOUT 
option to specify the tape device being used: 

amserv export (tapout 181 

In this example, the output from the AMSERV control statements in a file 
named EXPORT goes to a tape at virtual address 181. CMS prompts you to 
enter the ddname: 
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DHSAHS367R ENTER TAPE OUTPUT DDNAMES: 

After you enter the ddname specified on the FILE parameter in the AHSERV 
file and press the carriage return, the AMSERV command executes. 



Reading VSAH Tage Files 

When you create a tape in CHS using AMSERV, CHS writes a tape mark 
preceding each output file that it writes. When this same tape is read 
using AHSERV under CHS, the tape mark is automatically skipped, so you 
do not have to forward space the tape. If you read this tape in a real 
DOS/VS system, you should use a TLBL card that specifies a filename, but 
no file-id. 

Similarly, when you create a tape under a DOS/VS system using Access 
Hethod Services, if the tape is created with standard labels, CHS AHSERV 
has no difficulty reading it. 

The only time you should worry about positioning a tape created by 
AHSERV is when you want to read the tape using a method other than 
AHSERV, for example, the MOVEFILE command. Then, you must forward space 
the tape using the CHS TAPE command before you can read it. 

Defining OS Input and Output Files 

Note: This information is for OS/VS VSAH users only. DOS/VS VSAH users 
should refer to "Defining DOS Input and Output Files" for information on 
defining files for use with VSAH. 

If you are going to use Access Hethod Services to manipulate VSAH or SAH 
files or you are going to execute VSAH programs under CHS, you must use 
the DLBL command to define the input and output files. The basic format 
of the DLBL command is: 

DLBL ddname filemode DSN datasetname (options 

where ddname corresponds to the FILE parameter in the AHSERV file and 
datasetname corresponds to the entry name of the VSAH file, that is, the 
name specified in the NAHE parameter of an Access Hethod Services 
control statement. 

If you are using a CHS file for AHSERV input or output, use the CHS 
operand, and enter CHS file identifiers, as follows: 

dlbl mine a cms out filel (vsam 

The maximum length allowed for ddnames under CHS VSAH is 7 
characters. This means that if you have assigned 8-character ddnames (or 
filenames) to files in your programs, only the first 7 characters of 
each ddname are used. So, if a program refers to the ddname OUTPUTDD, 
you should issue the DLBL command for a ddname of OUTPUTD. Since you 
can encounter problems with a program that contains ddnames with the 
same first seven characters, you should recompile those programs using 
7-character ddnames. 

There are several options you can use when issuing the DLBL command 
to define VSAH input and output files. These are: 
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• VSAM, which you must use to indicate that the file is a VSAM file. 

Note: You do not have to use the VSAM option to identify a file as a 
VSAM file if you are using any of the other options listed here, 
since they imply that the file is a VSAM file. In addition, the 
ddnames (filenames) IJSYSCT and IJSYSUC also indicate that the file 
being defined is a VSAM file. 

• EXTENT, which you must use when you are defining a catalog or a VSAM 
data space; you are prompted to enter the volume information. 

• MULT, which you must use in order to access a multivolume VSAM file; 
you are prompted to enter the extent information. 

• CAT, which you can use to identify a catalog which contains the entry 
for the VSAM file you are defining. 

• BUFSP, which you can use to specify the size of the buffers VSAM 
should use during program execution. 



ALLOCATING EXTENTS ON OS DISKS AND MINIDISKS 

When you use Access Method Services to manipulate VSAM files under OS, 
you do not have to worry about allocating the real cylinders and tracks 
to contain the files. When you use CMS AMSERV, however, you are 
responsible for indicating which cylinders and tracks should contain 
particular VSAM spaces when you use the DEFINE control statement to 
define space. 

Extents for VSAM data spaces can be defined, in AMSERV files, in 
terms of cylinders, tracks, or records. Extent information you supply to 
CHS when executing AMSERV must always be in terms of tracks. When you 
define data spaces or unigue clusters, the extent information (number of 
cylinders, tracks, or records) in the AMSERV file must match the extents 
you supply when you issue the DLEL command to define the file. When you 
supply extent information for the master catalog, any extents you enter 
in excess of those reguired for the catalog are claimed by the catalog 
and used as data space. 

CMS does not make secondary space allocation for VSAM data spaces. 
If you execute an AMSERV file that specifies a secondary space 
allocation, CMS ignores the parameter. 

When you use the DLBL command to define VSAM data space, you must use 
the EXTENT option, which indicates to CMS that you are going to enter 
data extents. For example, if you enter 

dlbl space b (extent 

CMS prompts you to enter the extents: 

DMSDLB331R ENTER EXTENT SPECIFICATIONS: . 

When you enter the extents, you specify the relative track number of the 
first track of the extent, followed by the number of tracks. For 
example, if you are allocating an entire 2314 disk, you would enter 

20 3980 

(null line) 
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You can never write on cylinder r track 0; and, since VSAM data 
spaces must be allocated on cylinder boundaries, you should never 
allocate cylinder 0. Cylinder is often used for the volume table of 
contents (VTOC) , as well, so it is always best to begin defining space 
with cylinder 1. 

The list below shows the DASD devices supported by CMS VSAM, the 
number of cylinders on each that can be allocated for VSAM space, and 
the number of tracks per cylinder: 

Disk Cylinders Tjca/sks/Cjlinder 
2314/2319 200 " 20~ 
3330 Series 404 19 

3340 Model 35 348 12 

3340 Model 70 696 12 

You can determine which disk extents on an OS disk or minidisk are 
available for allocation by using the LISTDS command with the FREE 
option, which also indicates the relative track numbers, as well as 
actual cylinder and head numbers. 



USING VSAM CATALOGS 

While you are developing and testing your VSAM programs in CMS, you may 
find it convenient to create and use your own master catalog, which may 
be on a CMS minidisk. VSAM catalogs, like any other cluster, can be 
shared read-only among several users. 

You name the VSAM master catalog for your terminal session using the 

ddname IJSYSCT for the DLBL command. For example, if your VSAM master 

catalog is located on an OS disk you have accessed as a C-disk, you 
would enter 

dlbl ijsysct c dsn master catalog (perm 

You must define the master catalog at the start of every terminal 
session. If you are always using the same master catalog, you might 
include the DLBL command you need to define it in your PROFILE EXEC: 

ACCESS 555 C 

DLBL IJSYSCT C DSN MASTCAT (PERM 

You should use the PERM option so that you do not have to reset the 
■aster catalog assignment after clearing previous DLBL definitions. The 
command 

dlbl * clear 

clears all file definitions except those entered with the PERM option. 



Defining a Master Catalog 

The sample DLBL command used in the preceding example is almost 
identical with the one you would issue to define a master catalog using 
AMSERV. The only difference is that you must enter the EXTENT option so 
that you can list the data spaces that this master catalog is to 
control. 
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As an example, suppose that you have a 30-cylinder 3330 minidisk 
assigned to you to use for testing your VSAM programs under CMS. 
Assuming that the minidisk is in your directory at address 333, you 
should first access it: 

access 333 d 
D (333) R/W - OS 

If you formatted the minidisk yourself, you know what label you assigned 
it; if not, you can find out the label assigned to the disk by issuing 
the CHS command 

guery search 

The response might be 

USR191 191 A R/W 

VSAM03 333 C R/W - OS 

SYS109 190 S R/0 

SYS19E 19E Y/S R/O 

Use the volume label VSAM03 in the MASTCAT AMSERV file: 

DEFINE MASTERCATALOG - 
(NAME (MASTCAT ) - 
VOLUME (VSAM03) - 
CYL (4) - 
FILE (IJSYSCT) ) 

To find out what extents on this minidisk you can allocate for VSAM, use 
the LISTDS command with the FREE option: 

listds d (free 

The response from LISTDS might look like this: 

FREESPACE INFORMATION FOR 'D« DISK: 
CYL-HD (RELTRK) TO CYL-HD (RELTRK) TRACKS 
000 01 1 000 09 9 9 
000 11 11 029 18 569 560 

From this response , you can see that the VTOC is located on the first 
cylinder, so you can allocate cylinders 1 through 29 for VSAM: 

dlbl ijsysct c dsn mastcat (perm extent 
DMSDLB331R ENTER EXTENT SPECIFICATIONS: 
19 551 

(null line) 

After entering the extents, in tracks, giving the relative track number 

of the first track to be allocated followed by the number of tracks, you 

must enter a null line to complete the command. (A null line is reguired 

because, when you enter multiple extents, entries may be placed on more 
than one line.) 

Now you can issue the AMSERV command: 

amserv mastcat 

A Ready message with no return code indicates that the master catalog is 
defined. You do not need to reissue the DLBL command in order to 
identify the master catalog for additional AMSERV functions. 
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Defining User Catalogs 

You can use the AMSERV command to define private catalogs and spaces for 
them. The procedures for determining what space you can allocate are the 
same as those outlined in the example of defining a master catalog. 

To define a user catalog, you can assign any ddname you want: 

access 199 e 
listds e (free 



dlbl catl e dsn private catl (extent 

amserv usercat 

The file USERCAT AMSERV might contain the following: 

DEFINE USERCATALOG - 

(NAME (PRIVATE. CAT1) - 
FILE (CAT1) - 
CYL (4) - 
VOLUME (OSVSAM) - 
CATALOG (MASTCAT) ) 

After this AMSERV command has completed successfully you can use the 
catalog PRIVATE. CAT1 . When you define a file cataloged in it, you 
identify it using the CAT option on the DLBL command: 

dlbl file2 c dsn ? (cat catl 

Or, you can define it as a job catalog. 

Using a Job Catalog 

During a terminal session, you may be referencing the same private 
catalog many times. If this is the case, you can identify a job catalog 
by using the ddname IJSYSUC. Then, that catalog is searched during all 
subsequent jobs, unless you override it using the CAT option when you 
use the DLBL command to define a file. 

If you defined a user catalog (IJSYSUC) for a terminal session and 
you use the AMSERV command to access a VSAM file, the user catalog takes 
precedence over the master catalog. This means that for files that 
already exist, the job catalog is searched. When you define a cluster, 
it is cataloged in the job catalog, rather than in the master catalog, 
unless you use the CAT option to override it. CMS never searches more 
than one VSAM catalog. 

You should use the CAT option to name a catalog when the AMSERV file 
you are executing references, with the CATALOG parameter, a catalog that 
is not defined either as the master catalog or as a user catalog. 

If you want to use additional catalogs during a terminal session, you 
first define them just as you would any other VSAM file: 

dlbl mycat2 f dsn private cat2 (vsam 
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Then, when you enter the DLBL command for the VSAM file that is 
cataloged in PRIVATE. CAT2 use the CAT option to refer to the ddname of 
the catalog: 

dlbl input f dsn input file (cat mycat2 

If you want to stop using a job catalog defined with the ddname IJSYSUC, 
you can clear it using the CLEAR option of the DLBL command: 

dlbl ijsysuc clear 

or, you can assign the ddname IJSYSUC to some other catalog. If you 
clear the ddname for IJSYSUC, then the master catalog becomes the job 
catalog. 



Catalog Passwords 

When you define passwords for VSAM catalogs in CMS, or when you use CMS 
to access VSAM catalogs that have passwords associated with them, you 
must supply the password from your terminal when the AMSERV command 
executes. The message that you receive to prompt you for the password 
is the same message you receive when you execute Access Method Services: 

4221A ATTEMPT 1 OF 2. ENTER PASSWORD FOR JOB AMSERV FILE catalog 

When you enter the proper password, AMSERV continues execution. 



DEFINING AND ALLOCATING SPACE FOR VSAM FILES 

You can use CMS AMSERV to allocate additional data spaces for VSAM. To 
use the DEFINE SPACE control statement, you must have defined either the 
master catalog or a user catalog which will control the space, and you 
must have the volume or volumes on which the space is to be allocated 
mounted and accessed. 

For example, suppose you have an OS 3330 disk attached to your 
virtual machine at virtual address 255. After accessing the disk and 
determining the free space on it, you could create a file named SPACE 
AMSERV: 

DEFINE SPACE - 

(FILE (FILE1) - 
TRACKS (1900) - 
VOLUME (123456) - 
CATALOG (PRIVATE. CAT2 CAT2) ) 

To execute this AMSERV file, you must define PRIVATE. CAT2 using the 
ddname CAT2 , and then define the ddname for the file: 

access 255 c 

dlbl cat2 c dsn private cat2 (vsam 

dlbl filel c (extent cat cat2 

You do not need to enter a data set name to define the space. When CMS 
prompts you for the extents of the space, you can enter the extent 
specifications : 
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DMSDLB331R ENTER EXTENT SPECIFICATIONS: 
190 1900 



When you define space for VSAM, you should be sure that the VOLUMES 
parameter and the space allocation parameter (whether CYLINDER, TRACKS, 
or RECORDS) in the AMSERV file agree with the track information you 
provide in the DLBL command. 



Specif ying Multiple Extents 

When you are specifying extents for a master catalog, data space, or 
unigue file, you can specify up to 16 extents on a volume for a 
particular space. When prompted by CMS for the extents, you must 
separate the different extents by commas, or place them on different 
lines. To specify a range of extents in the above example, you could 
enter 

dlbl filel c (extent 
190 190, 570 190, 1900 1520 
(null line) 

— or — 

dlbl filel c (extent 
190 190 
570 190 
1900 1520 

(null line) 

Again, the first number entered for each extent represents the relative 
track for the beginning of the extent and the second number indicates 
the number of tracks. 



S.Eecify.incf Multivolume Extents 

You can define spaces that span up to nine volumes for VSAM files; all 
of the volumes must be accessed and assigned when you issue the DLBL 
command to define or identify the data space. 

You should remember, though, that if you are using AMSERV and you do 
not use the PRINT option, you must have a read/write CMS disk so that 
AMSERV can write the output LISTING file. 

If you are defining a new multivolume data space or unigue cluster, 
you must specify the extents on each volume that the data is to occupy 
(starting track and number of tracks) , followed by the disk mode letter 
at which the disk is assigned: 

access 135 b 

access 136 c 

access 137 d 

dlbl newfile b (extent 

DMSDLB331R ENTER EXTENT SPECIFICATIONS: 

100 60 b, 400 80 b, 60 40 d , 

2000 100 c 

(null line) 
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If you enter more than one extent on the same line, the extents must be 
separated by commas; if you enter a comma at the end of a line, it is 
ignored. Different extents for the same volume must be entered 
consecutively. Mote that in this example, the extent information is for 
2314 disks and that these extents are also on cylinder boundaries. 

When you enter multivolume extents, you do not have to enter a mode 
letter for those extents on the disk identified in the DLBL command. 
For the extents on disk B in the above example, you could enter 

dlbl newfile b (extent 

DMSDLB331R ENTER EXTENT SPECIFICATIONS: 

100 400 80, 60, 60 40 d 

2000 100 c 

(null line) 

If you make any errors issuing the DLBL command or extent 
information, you must re-enter the entire command sequence. 

II'MIIIIISG EXISTING MJLTIVOLUME FILES: When you issue a DLBL command to 
identify an existing multivolume VSAM file, you must use the MOLT option 
of the DLBL command sequence: 

dlbl old b1 dsn ? (mult 

DMSDLB220R ENTER DATASET NAME: 

vsamtest.file 

DMSDLB330R ENTER VOLUME SPECIFICATIONS: 

c, d 

e 

(null line) 

When you enter the DLBL command you should specify the mode letter for 
the first disk volume on the command line. When you enter the MULT 
option you are prompted to enter additional specifications for the 
remaining extents. In the above example, the data set has extents on 
disks accessed as B- , C- , D-, and E-disks. 



USING TAPE INPUT AND OUTPUT 

If you are using AMSERV for a function that requires tape input and/or 
output, you must have the tape(s) attached to your virtual machine. The 
valid addresses for tapes are 181, 182, 183, and 184. When referring to 
tapes, you can also refer to them using their CMS symbolic names TAP1, 
TAP2, TAP3, and TAP4. 

When you use AMSERV to create or read a tape, you supply the ddname 
for the tape device interactively, after you issue the AMSERV command. 
To indicate to AMSERV that you are using tape for input or output, you 
must use the TAPIN or TAPOUT option to specify the tape device being 
used: 

amserv export (tapout 181 

In this example, the output from an EXPORT function is to a tape at 
virtual address 181. CMS prompts you to enter the ddname: 

DMSAMS367R ENTER TAPE OUTPUT DDNAMES: 

After you enter the ddname for the tape file, AMSERV begins execution. 
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E^lililiS Tapes 

When you create a tape file using AMSEBV under CMS, CMS writes a tape 
mark preceding each output file. When CMS AMSERV is used to read this 
same file, it automatically skips past the tape mark to read the file. 
If you want to read the tape on a real OS/VS system, however, you must 
use the LABEL=(2,NL) parameter on the data definition (DD) card for the 
tape. 

If you are creating a tape under OS/VS Access Method Services to be 
read by CMS AMSERV, you must be sure to create the tape using standard 
labels so that CMS can read it properly. CMS will not be able to read a 
tape created with LABEL=(,NL) on the DD card. 

For CMS to read this tape for any other purpose (for example, to use 
the MOVEFILE command to copy it) , you must remember to forward space the 
file past the tape mark before beginning to read it. 



Using AMSERV Under CMS 

This section provides examples of AMSERV functions executed under CMS. 
The examples are applicable to both the CMS (OS) and CMS/DOS 
environments. You should be familiar with the material presented in 
either "Defining DOS Input and Output Files" or "Defining OS Input and 
Output Files," depending on whether you are a DOS or an OS user, 
respectively. For the examples shown below, command lines and options 
that are reguired only for CMS/DOS users are shaded. OS users should 
ignore these shaded entries. 



USING THE DEFINE AND DELETE FUNCTIONS 

When you use the DEFINE and DELETE control statements of AMSERV, you do 
not need to specify the DSN parameter on the DLBL command: 



fJiiiasitiiiM 



dlbl ljsysct c (perm extent 

If the above commands are executed prior to an AMSEBV command to define 
a master catalog, the DEFINE will be successful as long as you have 
assigned a data set name using the NAME parameter in the AMSERV file. 
The same is true when you define clusters, or when you use the DELETE 
function to delete a cluster, space, or catalog. 

When you do not specify a data set name, AMSERV obtains the name from 
the AMSERV file. In the case of defining or deleting space, no data set 
name is needed; the FILE parameter corresponding to the ddname is all 
that is necessary, and AMSERV assigns a default data set name to the 
space. 

When you define space on a minidisk using AMSERV, CMS does not check 
the extents you specify to see whether they are greater than the number 
of cylinders available. as long as the starting cylinder is a valid 
cylinder number and the extents you specify are on cylinder boundaries, 
the DEFINE function completes successfully. However, you receive an 
error message when you use an AMSERV function that tries to use this 
space. 
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P§fi2i£3 § Sub allocated Cluster 

To define a cluster for VSAM space that has already been allocated, you 
need (1) an AMSERV file containing the control statements necessary for 
defining the cluster, and (2) the master catalog (and, perhaps, user 
catalog) volume, which will point to the cluster. The volume on which 
the cluster is to reside does not have to be online when you define a 
suballocated cluster. 

For example, the file CLUSTER AMSERV contains the following: 

DEFINE CLUSTER ( NAME (EOOK.LIST) - 

VOLUMES (123456) - 

TRACKS (40) - 

FILE (BOOK) - 

KEYS (14,0) RECORDSIZE (120,132) ) - 
DATA (NAME (BOOK . LIST. DATA) ) - 
INDEX (NAME (BOOK . LIST . INDEX) ) 

To execute this file, you would need to enter the following command 
seguence (assuming that the master catalog, on volume 123456, is in your 
virtual machine at address 310) : 

access 310 b 

assgn syscat b; 

dlbl ijsysct b (perm syscfat 

amserv cluster 

Note that to define a suballocated cluster, you do not need to provide a 
DLBL command to define it to AMSERV. 



5§fiBisa £ U£i9ii€! Cluster 

For a unigue cluster (one defined with the UNIQUE attribute) , you must 
define the space for the cluster at the same time you define its name 
and attributes; thus the volume or volumes on which the cluster is to 
reside must be mounted and accessed when you execute the AMSERV 
command. You must supply extent information for the clusters data and 
index portions separately. 

To execute an AMSEIV file named UNIQUE which contains the following 
(the ellipses indicate that the AMSERV file is not complete) : 

DEFINE CLUSTER - 

(NAME (PAYROLL) ) - 
DATA ( FILE (UDATA) - 
UNIQUE - 

VOLUMES (567890) - 
CYLINDERS (40) - 
... ) " 
INDEX ( FILE (UINDEX) ) - 
UNIQUE - 

VOLUMES (567890) - 
CYLINDERS (10) - 
... ) 
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the command sequence should be: 
access 350 c 



c 

dibl udata c (extent sys004 
DHSDLB331BENTER EXTENT SPECIFICATIONS: 
800 800 c sysOOU 
dlbl uindex c (extent sysOOU 
600 200 c sys004 
amserv unique 



Deleting Clusters, Spaces, and Catalogs 

When you use AMSERV to delete a VSAM cluster, the volume containing the 
cluster does not have to be accessed unless the volume also contains the 
catalog in which the cluster is defined. In the case of data spaces and 
user catalogs, or the master catalog, however, the volume (s) must be 
mounted and accessed in order to delete the space. 

When you delete a cluster or a catalog, you do not need to use the 
DLBL command, except to define the master catalog; AMSERV can obtain the 
necessary file information from the AMSERV file. In the case of data 
spaces, you must supply a ddname (filename) with the DLBL command, but 
you do not need to use the DSN parameter. 

You should be particularly careful when you are using temporary disks 
with AMSERV, that you have not cataloged a temporary data space or 
cluster in a permanent catalog. You will not be able to delete the space 
or cluster from the catalog. 



USING THE REPRO, IMPORT, AND EXPORT (OR EXPORTRA/IMPORTRA) FUNCTIONS 

You can manipulate VSAM files in CMS with the REPRO, IMPORT, and EXPORT 
functions of AMSERV. You can create VSAM files from sequential tape or 
disk files (on OS, DOS, or CMS disks) using the REPRO function. Using 
REPRO, you can also copy VSAM files into CMS disk files or onto tapes. 
For the IMPORT/EXPORT process, you have the option (for smaller files) 
of exporting VSAM files to CMS disks, as well as to tapes. 

You cannot, however, use the EXPORT function to write files onto OS 
or DOS disks. Nor can you use the REPRO function to copy ISAM (indexed 
sequential) files into VSAM data sets, since CMS cannot read ISAM 
files. 

You cannot use the ERASE or PURGE options of the EXPORT command if 
you are exporting a VSAM file from a read-only disk. The export 
operation succeeds, but the listing indicates an error code 184, meaning 
that the erase function could not be performed. 

You should not use an EXPORT DISCONNECT function from a CMS minidisk 
and try to perform an IMPORT CONNECT function for that data set onto an 
OS system. OS incorrectly rebuilds the data set control block (DSCB) 
that indicates how much space is available. 

The AMSERV file below gives an example of using the REPRO function to 
copy a CMS sequential file into a VSAM file. The CMS input file must be 
sorted in alphameric sequence before it can be copied into the VSAM 
file, which is a keyed sequential data set (KSDS) . The VSAM cluster, 
NAME. LIST, is defined in an AMSERV file named PAYROLL: 
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DEFINE CLUSTER ( NAME (NAME. LIST ) - 

VOLUMES (CMSDEV) - 

TRACKS (20) - 

FILE (BOOK) - 

KEYS (14,0) - 

RECORDSIZE (120,132) ) - 
DATA (NAME (NAME. LIST. DATA) ) - 
INDEX (NAME (NAME. LIST. INDEX ) ) 

To sort the CMS file, create the cluster and copy the CMS file into it, 
use the following commands: 

sort name list a name sort a 
DMSSRT604R ENTER SORT FIELDS: 
1 14 
access 135 c 

dlbl ijsysct c (perm 
amserv payroll 

dlbl sort a cms name sort 

dTbTname"**^ dsn name list (flSQlSZi vsam 
amserv repro 

The file REPRO AMSERV contains: 

REPRO INFILE ( SORT - 

ENV (RECORDFORMAT (F) - 
BLOCKSIZE (80) - * 
PDEV (3330) ) ) - 
OUTFILE (NAME) 

When you use the REPRO, IMPORT, or EXPORT functions with tape files, 
you must remember to use the TAPIN and TAPOUT options of the AMSERV 
command. These options perform two functions: they allow you to specify 
the device address of the tape, and they notify AMSERV to prompt you to 
enter a ddname. 

In the example below, a VSAM file is being exported to a tape. The 
file, TEXPORT AMSERV, contains: 

EXPORT BAME.LIST - 

INFILE (NAME) - 

OUTFILE (TAPE ENV (PDEV (2400) ) ) 

To execute this AMSERV, you enter the commands as follows: 



dlbl name c (BWQ<& vsam 
amserv texport (tapout 181 
DMSAMS367R ENTER TAPE OUTPUT DDNAMES: 
tape 



WRITING EXECS FOR AMSERV AND VSAM 



You may find it convenient to use EXEC procedures for most of your 
AMSERV functions, as well as setting up input and output files for 
program execution, and executing your VSAM programs. If, for example, a 
particular AMSERV function reguires several disks and a number of DLBL 
statements, you can place all of the reguired commands in an EXEC file. 
For example, if the file below is named SETUP EXEC: 
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ACCESS 135 B 
ACCESS 136 C 
ACCESS 137 D 
ACCESS 3.00 G 



DLBL IJS YSCT G (PERM 

DLBL m t F II E 1 B D S M FIRST FILE (VSAM 

DLBL FILE2 C DSN SECOND FILE (VSAM 



DLBL FILE3 D DSN THIRD FILE (VSAM 
AMSERV MULTFILE 

to invoke this sequence of commands, all you have to enter is the name 
of the EXEC: 

setup 

If you place, at the beginning of the EXEC file, the EXEC control 
statement 

SERROR SEXIT SRETCODE 

then, you can be sure that the AMSERV command does not execute unless 
all of the prior commands completed successfully. 

For those AMSERV functions that issue response messages, you can use 
the 6STACK EXEC control statement. For example, 

SERROR SEXIT SRETCODE 
ACCESS 305 D 



DLBL OUTPUT D (VSAM 

SERROR SCOHTINUE 

SSTACK TAPE 

AMSERV TIMPORT (TAPIN 181 

SIF SRETCODE ME TYPE TIMPORT LISTING 

TAPE REM 

SEXIT 

When the AMSERV command in the EXEC is executed, the request for the 
tape ddname is satisfied immediately, by the response stacked with the 
SSTACK statement. 

If you are executing a command that accepts multiple response lines, 
you have to stack a null line as follows: 



SSTACK C 

SSTACK 

DLBL MULTFILE B (MULT 

Mote: You can use the SBEGSTACK control statement to stack a series of 
responses in an EXEC, but you must use SSTACK to stack a null line. 
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Section 11. How VM/370 Can Help You Debug Your Programs 



Debugging is a critical part of the program development process. When 
you encounter problems executing application programs, or when you want 
to test new lines of code, you can use a variety of CP and CMS debugging 
commands and technigues to explore your program while it is executing. 

You can interrupt the execution of a program to examine and change 
your general registers, storage areas, or control words such as the 
Program Status Word (PSW) , and then continue execution. Also, you can 
trace the execution of a program closely, so you can see where branches 
are being taken, and when supervisor calls or I/O interrupts occur. 

In many cases, you may never need to look at a dump of a program to 
identify a problem. 



Preparing To Debug 

Before beginning to debug a program, you should have a current program 
listing for reference. When you use VM/370 to debug a program, you can 
monitor program execution, instruction by instruction, so you must have 
an accurate list of instruction addresses and addresses of program 
storage areas. You can obtain a listing of your program by using the 
PRINT command to print the LISTING file created by the assembler or 
compiler. To determine the virtual storage locations of program entry 
points, use the LOAD MAP file created by the LOAD and INCLUDE commands. 
If you are a CMS/DOS user, use the linkage editor map produced by the 
DOSLKED command. 

If the program that you are debugging creates printed or punched 
output, and you will be executing the program repeatedly, you may not 
wish all of the output printed or punched. You should place your 
printer or punch in a hold status, so that any files spooled to these 
devices are not released until you specifically request it: 

cp spool printer hold 
cp spool punch hold 

When you are finished debugging you can use the CP QUERY command to see 
what files are being held and then you can select which files you may 
want to purge or release. 



When a Program Abends 

The most common problem you might encounter is an abnormal termination 
resulting from a program interruption. When a program running in a CMS 
virtual machine abnormally terminates (abends), you receive, at your 
terminal, the message 

DMSITP141T exception EXCEPTION OCCURRED AT address IN ROUTINE name 

and your virtual machine is returned to the CMS environment. From the 
message you can determine the type of exception (program check, 
operation, specification, and so on), and, often, the instruction 
address in your program at which the error occurred. 
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Sometimes this is enough information for you to correct the error in 
your source program, recompile it and attempt to execute it again. 

When this information does not immediately identify the problem in 
your program, you can begin debugging procedures using VM/370. To 
access your program's storage areas and registers you can enter the 
command 

debug 

immediately after receiving the abend message. This command places your 
virtual machine in the debug environment. 

To check the contents of general registers through 15, issue the 
DEBUG subcommand 

gpr 15 

If you want to look at only one register, enter 

gpr 3 

You might also wish to check the Program Status Word (PSW) . Use the PSW 
subcommand: 

psw 

You can examine storage areas in your program using the X subcommand: 

X 201AC 20 

In this example, the subcommand reguests a display of 20 bytes, 
beginning at location 20 1AC in your program. User programs executed in 
CMS are always loaded beginning at location X'20000' unless you specify 
a different address on the LOAD or FETCH command. To identify the 
virtual address of any instruction in a program, you only need to add 
20000 to the hexadecimal instruction address. 



RESUMING EXECUTION AFTER A PROGRAM CHECK 

On occasion, you will be able to determine the cause of a program check 
and continue the execution of your program. There are DEBUG subcommands 
you can use to alter your program while it is in storage and resume 
execution. 

If, for example, the error occurred because you had forgotten to 
initialize a register to contain a zero, you could use the DEBUG 
subcommand SET to place a zero in the register, and then resume 
execution with the GO subcommand. You can use the GO subcommand to 
specify the instruction address to which you want execution to begin: 

set gpr 11 0000 
go 200B0 

An alternate method of specifying a starting address for execution to 
resume is by using the SET subcommand to change the last word of the 
PSW: 

set psw 000200B0 
go 
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If your program executes successfully, you can then make the 
necessary changes to your source file, recompile, and continue testing. 



Using DEBUG Subcommands to Monitor Program Execution 

The preceding examples did not represent a wide range of the 
possibilities for DEBUG subcommands. Nor do they represent the only way 
to approach program debugging. Some additional DEBUG subcommands are 
illustrated below. For complete details in using these subcommands, 
refer to the VM/370: CMS Command ,§nd Macro Reference. 

When you prepare to debug a program with known problems, or when you 
are beginning to debug a program for the first time, you might want to 
stop program execution at various instructions, and examine the 
registers, constants, buffers, and so on. To temporarily stop program 
execution, use the BREAK subcommand to set breakpoints. you should set 
breakpoints after you load the program into storage, but before you 
begin executing it. You can set up to 16 breakpoints at one time. For 
each breakpoint, you assign a value (id), and an instruction address: 

load myprog 

debug 

break 20BC0 

break 1 20C10 

break 2 20D00 

Then, you can return to CMS and begin execution: 

return 
start 

When the first breakpoint in this example is encountered, you receive 
the messages 

DEBUG ENTERED. 
BREAKPOINT 1 AT 20BC0 

Then, in the debug environment, use the subcommands GPR, CSW, CAW, PSW, 
and X to display registers, control words, or storage locations. 

You can resume program execution with the GO subcommand: 

go 

If, at any time, you decide that you do not want to finish executing 
your program, but want to return to the CMS environment immediately, you 
must use the HX subcommand 

hx 

There are three subcommands you can use to exit from the debug 
environment: 

1. RETURN, to return to the CMS environment when DEBUG is entered with 
the DEBUG command. 

2. GO, to resume program execution when it has been interrupted by a 
breakpoint. 

3. HX, to halt program execution entirely and return to the CMS 
environment. 
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If you try to leave the debug environment with the wrong subcommand you 
receive the message 

INCORRECT DEBUG EXIT 

and you have to enter the proper subcommand. 



OSING SYMBOLS WITH DEBUG 



To simplify the process of debugging in the CMS debug environment, you 
can use the ORIGIN and DEFINE subcommands. The ORIGIN command allows 
you to set an instruction location to serve as the base for all the 
addresses you specify. For example, if you specify 

origin 20000 

then, to refer to your virtual storage location 201BC, you only need to 
enter 

x 1bc 

By setting the DEBUG origin at your program^ base address, you can 
refer to locations in your program by the virtual storage numbers in the 
listing, rather than having to compute the actual virtual storage 
address each time. The current DEBUG origin stays in effect until you 
set it to a different value or until you reload CMS (with the IPL 
command) . 

You can use the DEFINE subcommand to assign symbolic names to storage 
locations so that you can reference those locations by symbol, rather 
than by storage address. For example, suppose that during a DEBUG 
session you will repeatedly be examining three particular storage 
locations labeled in your program NAME1, NAME2, and NAME3. They are at 
locations 20EF0, 20EFA, and 20F04. Enter: 

load nameprog 

debug 

origin 20000 

define namel EF0 10 

define name2 EFA 10 

define name3 F0U 10 

break 1 aOU 

return 

start 



When the specified breakpoint is 
storage areas by entering: 

x namel 
x name2 
x name3 



encountered, you can examine these 



You can also refer to these symbols by 
subcommand: 

store name2 c4c5c3c5c1eUe5d6c9d9 



name when you use the STORE 



The names you specify do not have to be the same as the labels in the 
program; you can define any name up to 8 characters. 

Figure 17 summarizes the DEBUG subcommands. 
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Subcommand Format 



Function 



BReak 



id ( symbol ) 
\ hexloc J 



CAW 



CSH 



r t 

DEFine symbol hexlcc |bytecount| 

I it I 

L J 



r r i t 

DUmp |symbol1 |symbol2| [ident] | 

Ihexlod |hexloc2| | 

I | * | | 

«• •- 32 J J 



r t 

GO |symbol| 
|hexloc| 

L J 

GPR regl [reg2 ] 



Stops program execution at the 
specified breakpoint. 

Displays the contents of the 
Channel Address Word. 

Displays the contents of the 
Channel Status Word. 



Assigns a symbolic name to the 
virtual storage address. 



Dumps the contents of specified 
virtual storage locations to the 
virtual spooled printer. 



Returns control to your program 
and starts execution at the 
specified location. 



Displays the contents of the 
specified general registers. 



HX 



Halts execution and returns to 
the CMS command environment. 



ORigin |symbol| 
| hexloc | 
I | 

L J 



Specifies the base address to be 
added to locations specified in 
other DEBUG subcommands. 



PSW 



RETurn 



Displays the contents of the old 
Program Status Word. 



Exits from debug environment to 
the CMS command environment. 



SET ( CAW hexinfo 

CSW hexinfo [hexinfo] 
PSW hexinfo [hexinfo] 
GPR reg hexinfo [hexinfo] 

STore ( symbol) hexinfo [hexinfo] 
\ hexloc J 



Changes the contents of specified 
control words or registers. 



Stores up to 12 bytes of informa- 
tion starting at the specified 
virtual storage location. 



r i 

X (symbol | n | 

I ie n^t h | 

L J 

r n 

hexloc | n | 

I ft I 

L J 



Examines virtual storage 
locations. 



Figure 17. Summary of DEBUG Subcommands 
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What To Do When Your Program Loops 

If, when your program is executing, it seems to be in a loop, you should 
first verify that it is looping, and then interrupt its execution and 
either (1) halt it entirely and return to the CMS environment or (2) 
resume its execution at an address outside of the loop. 

The first indication of a program loop may be either what seems to be 
an unreasonably long processing time, or, if you have a blip character 
defined, an inordinately large number of blips. 

You can verify a loop by checking the PSW frequently. If the last 
word repeatedly contains the same address, it is a fairly good 
indication that your program is in a loop. You can check the PSW by 
using the Attention key to enter the CP environment. You are notified 
by the message 

CP 

that your virtual machine is in the CP environment. You can then use 
the CP command DISPLAY to examine the PSW 

cp display psw 

and then enter the command BEGIN to resume program execution: 

cp begin 

If you are checking for a loop, you might enter both commands on the 
same line using the logical line end: 

cp d p#b 

When you have determined that your program is in a loop, you can halt 
execution using the CMS Immediate command HX. To enter this command, 
you must press the Attention key once to interrupt program execution, 
then enter 

hx 

If you want your program to continue executing at an address past the 
loop, you can use the CP command BEGIN to specify the address at which 
you want to continue execution: 

cp begin 20cd0 

Or, you could use the CP command STORE to change the instruction address 
in the PSW before entering the BEGIN command: 

cp store psw 20cd0#begin 



Tracing Program Activity 

When your program is in a loop, or when you have a program that takes an 
unexpected branch, you might need to trace the execution closely to 
determine at what instruction the program goes astray. There are two 
commands you can use to do this. The SVCTRACE command is a CMS command 
which traces all SVCs (supervisor calls) in your program. The TRACE 
command is a CP command which allows you to trace different kinds of 
information, including supervisor call instructions. 
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USING THE CP TRACE COMMAND 

You can trace the following kinds of activity in a program using the CP 
TRACE command : 

• Instructions 

• Branches 

• Interrupts (including program, external, I/O and SVC interrupts) 

• I/O and channel activity 

When the TRACE command executes, it traces all your virtual machine's 
activity; when your program issues a supervisor call, or calls any CMS 
routine, the TRACE continues. 

You can make most efficient use of the TRACE command by starting the 
trace at a specific instruction location. You should set an address 
stop for the location. For example, if you are going to execute a 
program and you want to trace all of the branches made, you would enter 
the following sequence of commands to begin executing the program and 
start the trace: 

load progress 

cp adstop 20004 

start 

ADSTOP AT 20004 

cp trace branch 

cp begin 

Now, whenever your program executes a branch instruction, you receive 
information at the terminal that might look like this: 

02001E BALR 05E6 ==> 020092 

This line indicates that the instruction at address 200 1E resulted in a 
branch to the address 020092. When this information is displayed, your 
virtual machine is placed in the CP environment, and you must use the 
BEGIN command to continue execution: 

cp begin 

When you locate the branch that caused the problem in your program, you 
should terminate tracing activity by entering 

cp trace end 

and then you can use CP commands to continue debugging or you can use 
the EXTERNAL command to cause an external interrupt that places your 
virtual machine in the debug environment: 

cp external 

You receive the message 

DEBUG ENTERED. 
EXTERNAL INTERRUPT 

And you can use the DEBUG subcommands to investigate the status of your 
program. 
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Q2E£l2iIiB3 a CP Trace 

There are several things you can do to control the amount of information 
you receive when you are using the TRACE command, and how it is 
received. For example, if you do not want program execution to halt 
every time a trace output message is issued, you can use the RUN option: 

cp trace svc run 

Then, you can halt execution by pressing the Attention key when the 
interrupt you are waiting for occurs. You should use this option if you 
do not want to halt execution at all, but merely want to watch what is 
happening in your program. 

Similarly, if you do not reguire your trace output immediately, you 
can specify that it be directed to the printer, so that your terminal 
does not receive any information at all: 

cp trace inst printer 

When you direct trace output to a printer, the trace output is mixed in 
with any printed program output. If you want trace output separated 
from other printed output, use the CP DEFINE command to define a second 
printer at a virtual address lower than that of your printer at 00E. For 
example: 

cp define printer 006 

Then, trace output will be in a separate spool file. CMS printed output 
always goes to the printer at address 00E. 

When you finish tracing, use the CP CLOSE command to close the 
virtual printer file: 

cp close e 

— or — 

cp close 006 

If you want trace output at the printer and at the terminal, you can use 
the BOTH option: 

cp trace all both 



Suspending Tracing 

If you are debugging a program that does a lot of I/O, or that issues 
many SVCs, and you are tracing instructions or branches, you might not 
wish to have tracing in effect when the supervisor or I/O routine has 
control. When you notice that addresses being traced are not in your 
program, you can enter 

cp trace end 

and then set an address stop at the location in your program that 
receives control when the supervisor or I/O routine has completed: 

cp adstop 20688 
begin 
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Then, when this address is encountered, you can re-enter the CP TRACE 
command. 



USING THE SVCTRACE COMMAND 

If your program issues many SVCs, you may not get all of the information 
you need using the CP TRACE command. The SVCTRACE command is a CMS 
command, which provides more detailed information about all SVCs in your 
program, including register contents before and after the SVC, the name 
of the called routine, and the location from which it was called, and 
the contents of the parameter list passed to the SVC. 

The SVCTRACE command has only two operands, ON and OFF, to begin and 
end tracing. SVCTRACE information can be directed only to the printer, 
so you do not receive trace information at the terminal. 

Since the SVCTRACE command can only be entered from the CMS 
environment, you must use the Immediate commands SO (suspend tracing) or 
HO (halt tracing) if you want tracing to stop while a program is 
executing. Use the Immediate command RO to resume tracing. 

Since the CMS system is "SVC- driven" , this debugging technigue can be 
useful, especially, when you are debugging CMS programs. For more 
information on writing programs to execute in CMS, see "Section 13. 
Programming for the CMS Environment." 



Using CP Debugging Commands 

In addition to the CMS debugging facilities, there are CP commands that 
you can use to debug your programs. These commands are: 

• DISPLAY, which you can use to examine virtual storages, registers, or 
control words, like the PSW. 

• AESTOP, which you can use to set an instruction address stop in your 
program. 

• STORE, which you can use to change the contents of a storage 
location, register, or control word. 

When you use the display command, you can reguest an EBCDIC translation 
of the display by prefacing the location you want display with a "T": 

cp display t20000.10 

This command requests a display of X'10' (16) bytes beginning at 
location X 1 20000'. The display is formatted 4 words to a line, with 
EBCDIC translation at the left, much as you would see it in a dump. 

You can also use the DISPLAY command to examine the general 
registers. For example, the commands: 

cp display g 
cp display g1 
cp display g2-5 

result in displays of all the general registers, of general register 1, 
and of a range of registers 2 through 5. 
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The DISPLAY command also displays the PSW, CAW, and CSW: 

cp display psw 
cp display caw 
cp display csw 

With the STORE command, you can change the contents of registers, 
storage areas, or the PSW. 

As you can see, the CMS DEBUG subcommands and the CP commands ADSTOP, 
DISPLAY, and STORE, have many duplicate functions. The environment you 
choose to work in, CP or debug, is a matter of personal preference. The 
differences are summarized in Figure 18. What you should be aware of, 
however, is that you should never attempt to use a combination of CP 
commands and DEBUG subcommands when you are debugging a program. Since 
DEBUG itself is a program, when it is running (that is, when you are in 
the debug environment) , the registers that CP recognizes as your virtual 
machine's registers are actually the registers being used by DEBUG. 
DEBUG saves your program's registers and PSW and keeps them in a special 
save area. Therefore, if you enter the DEBUG and CP commands to display 
registers, you will see that the register contents are different: 

gpr 15 

Hep d 9 



DEBUGGING WITH CP AFTER A PROGRAM CHECK 

When a program that is executing under CMS abends because of a program 
check, the DEBUG routine is in control and saves your program's 
registers, so that if you want to begin debugging, you must use the 
DEBUG command to enter the debug environment. 

You can prevent DEBUG from gaining control when a program interrupt 
occurs by turning on the wait bit in the program new PSW (location X'68' 
in low storage) : 

cp store 68 00020000 

You should do this before you begin executing your program. Then, a 
program check occurs during execution, when CP tries to load the program 
new PSW, the wait bit forces CP into a disabled wait state and you 
receive the message 

DMKDSP450W CP ENTERED; DISABLED WAIT PSW 

All of your program's registers and storage areas remain exactly as they 
were when program interrupt occurred. The PSW that was in effect when 
your program was interrupted is in the program old PSW, at location 
X'28». Use the DISPLAY command to examine its contents: 

cp display 28.8 

The program new PSW, or the PSW you see if you enter the command DISPLAY 
PSW contains the address of the EEBUG routine. 

If, after using CP to examine your registers and storage areas, you 
can recover from the problem, you must use the STORE command to restore 
the PSW, specifying the address of the instruction just before the one 
indicated at location X'28'. For example, if the instruction address in 
your program is X'566' enter: 



224 IBM VM/370: CMS User's Guide 



cp store psw 20566 
cp begin 

In this example, setting the first word of the PSW to turns the wait 
bit off, so that execution can resume. 

Program Dumps 

When a program you execute under CMS abnormally terminates, you do not 
automatically receive a program dump. If, after attempting to use CMS 
and CP to debug interactively, you still have not discovered the 
problem, you may want to obtain a dump, you might also want to obtain a 
dump if you find that you are displaying large amounts of information, 
which is not practical on a terminal. 

Depending on whether you are using CMS DEBUG or CP to do your 
debugging, you can use the DUMP command to specify storage locations you 
want printed. The formats of the DUMP command (CP) and the DUMP 
subcommand (DEBUG) are a little different. See VM/370: CMS Command and 
Hi-Cro Reference for a discussion of the DEBUG "subcommand, DUMP; see 
X!l2370:~CP Command Reference for General Users for a discussion of the 
CP DUMP command. 

In either event, you can selectively dump portions of your virtual 
storage, your entire virtual storage area, or portions of real storage. 
For example, to dump the virtual storage space that contains your 
program from the debug environment you would enter 

cp dump 20000 20810 

The second value depends upon the size of your program. 

From the CP environment, enter 

cp dump t20000-20810 

The CP DUMP command allows you to reguest EBCDIC translation with the 
hexadecimal dump. The dump produced by the DEBUG subcommand does not 
provide EBCDIC translation. 

Debugging Modules 

You can debug nonrelocatable MODULE files (created with the GENMOD 
command) in the same way you can debug object modules (TEXT files) . 

To load the MODULE into storage, use the LOADMOD command: 

loadmod mymod 
cp adstop 201C0 
start 

If you make any changes to the module while it is in your virtual 
storage area and then issue the GENMOD command, the changes are a 
permanent part of the executable module: 

loadmod mymod 

cp store 201C0 0002 

genmod mymod 

To debug MODULE files in this manner, you must have a listing of the 
program as it existed when the module was created. 
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Comparison Of CP And CMS Facilities For Debugging 

If you are debugging problems while running CMS, you can choose the CP or CMS debugging 
tools. Refer to Figure 18 for a comparison of the CP and CMS debugging tools. 
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CP 



CMS 
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Can set only one address stop at a time. 



The dump is printed in hexadecimal format 
with EBCDIC translation. The storage ad- 
dress of the first byte of each line is 
identified at the left. 
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with EBCDIC translation. The CP command 
displays storage keys, floating— point regi- 
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Can set up to 16 address stops 
at a time. 



The dump is printed in hexa- 
decimal format. The storage 
address of the first byte of 
each line is identified at the 
left. The contents of general 
and floating-point registers 
are printed at the beginning 
of the dump. 



The display is typed in hexa- 
decimal format. The CMS com- 
mands do not display storage 
keys, floating— point registers 
or control registers as the CP 
command does. 



The CMS command stores up to 
12 bytes of information. CMS 
stores data in the general 
registers but not in the 
floating-point or control reg- 
isters. CMS stores data in the 
PSW, CAW, and CSW. 



Tracing | CP traces: 

infonoa- | • All interrupts, instructions, and 

tion. I branches 

• SVC interrupts 

• I/O interrupts 

• Program interrupts 

• External interrupts 

• Privileged instructions 

• All user I/O operations 

• Virtual and real CCW's 

• All instructions 

The CP trace is interactive. You can stop 
it and display other fields. 

Figure 18. Comparison of CP and CMS Facilities for Debugging 



CMS traces all SVC interrupts, 
CMS displays the contents 
of general and floating-point 
registers before and after 
a routine is called. The para- 
meter list is recorded before 
a routine is called. 
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What Your Virtual Machine Storage Looks Like 

Figure 19 illustrates a simplified CMS storage map. The portion of 
storage that is of most concern to you is the user program area, since 
that is where your programs are loaded and executed. The user program 
area and some of the other areas of storage shown in the figure are 
discussed below in general terms. 

When you issue a LOAD command (for OS or CMS programs) or a FETCH 
command (for DOS programs) , and you do not specify the ORIGIN option, 
the first, or only, program you load is loaded at location X'20000', the 
beginning of the user program area. 

The upper limit, or maximum size, of the user program area is 
determined by the storage size of your virtual machine. You can find 
out how large your virtual machine is by using the CP QUERY command: 

cp guery virtual storage 

If you need to increase the size of your virtual machine, then you 
must use the CP command DEFINE. For example 

cp define storage 1024k 

increases the size of your virtual machine to 1024K bytes. If you are 
in the CMS environment when you enter this command, you receive a 
message like: 

STORAGE = 01024K 

DMKDSP450W CP ENTERED; DISABLED WAIT PSW '00020000 00000000 1 

and you must reload CMS with the IPL command before you can continue. 

You might need to redefine your virtual machine to a larger size if 
you execute a program that issues many reguests for free storage, with 
the OS GETMAIN or DOS/VS GETVIS macros. CMS allocates this storage from 
the user program area. 

At the top of the user program area are the loader tables, that are 
used by the CMS loader to point to programs that have have been loaded. 
You can increase the size of this area with the CMS SET LDRTBLS command. 
If you use the SET LDRTBLS command, you should issue it immediately 
after you IPL CMS. 

The transient program area is used for loading and executing 
disk-resident CMS MODULE files that have been created using the ORIGIN 
TRANS option of the LOAD command, followed by the GENMOD command. For 
■ore information on CMS MODULE files and the transient area, see 
"Executing Program Modules" in "Section 13. Programming for the CMS 
Environment." 



SHARED AND NONSHARED SYSTEMS 

The areas in storage labelled in Figure 19 as the CMS nucleus and the 
DCSS are system programs that are loaded by various types of reguests. 
When you enter the command 

cp ipl cms 
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Loader Tables 



User Program Area 



CHS Nucleus 



Transient Program Area 



Free storage used by 
CMS routines 

System Control Blocks, 
Pointers, Flags 

Figure 19. Simplified CMS Storage Map 
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virtual machine 
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the area shown as the CMS nucleus is loaded with the CMS system, which 
is known to CP by its saved name, CMS. This saved system is a copy of 
the CMS system that is available for many users to share. When ycu are 
using CMS, you share it with other users who have also issued the IPL 
command to load the saved CMS system. By having many users share the 
same system, CP can manage system resources more efficiently. 

Under some circumstances, you may need to load the CMS system into 
your virtual machine by entering the IPL command as follows: 

cp ipl 190 

This IPL command leads the CMS system by referring to its virtual 
address, which in most installations is 190. The copy of CMS you load 
this way is nonshared; it is your own copy, but it is the same system, 
functionally, as the saved system CMS. 

Some of the CP and CMS debugging commands do not allow you to trace 
or store information that is contained in shared areas of your virtual 
machine. For example, if you have entered the command 

cp trace inst 
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to trace instructions in your virtual machine, some of the instructions 
may be located in the CMS nucleus. If you have a shared copy of CMS, you 
receive a message like 

DMKVMA181E SHARED SYSTEM XCMS REPLACED KITH NONSHARED COPY 

and CP loads a copy of CMS for you that you do not share with other 
users. 



Discontiguous Shared Segments (DCS.SJ 

Some CMS routines and programs are stored on disks, and loaded into 
storage as needed. These segments include the CMS Editor, EXEC 
processor, and OS simulation routines; CMS/DOS; VSAM; and Access Method 
Services. Beyond the end of your virtual machine address space is an 
area of storage into which these segments are loaded when you need 
them. Since this area is not contiguous with your virtual storage, the 
segments that are loaded in this area are called discontiguous shared 
segments. 

These segments are loaded only when you need them, and are released 
from the end of your virtual machine when you are through using them. 
Like the CMS system, they are saved systems, and can be shared by many 
users. For example, whenever you issue the EDIT command the segment 
named CMSSEG is loaded; when you enter the EDIT subcommands FILE or 
QUIT, the saved system CMSSEG is released. The other segments are named 
CMSDOS (for CMS/DOS) , CMSVSAM (for VSAM interfaces) , and CMSAMS (for 
Access Method Services Interfaces) . 

If during the course of debugging, you need a nonshared copy of one 
of these segments, you can use the SET command with the NONSHARE 
operand, for example 

set nonshare cmsseg 

If you do not specifically request a nonshared copy before you issue a 
command that alters a shared segment, CP replaces the shared copy with a 
nonshared copy for you and issues the DMKVMA181E message. 

For additional information on saved systems, discontiguous shared 
segments, and CMS virtual storage, see the VM/370: System Programmers 
Guide. ~" 



Section 11. How VM/370 Can Help You Debug Your Programs 229 



Section 12. Using the CMS Batch Facility 



The CMS Batch Facility provides a way of submitting jobs for batch 
processing in CMS. You can use the CMS Batch Facility when: 

• You have a job (like an assembly or execution) that takes a lot of 
time, and you want to be able to use your terminal for other work 
while the time-consuming job is being run. 

• You do not have access to a terminal. 

The CMS Batch Facility is really a virtual machine, generated and 
controlled by the system operator, who logs on VM/370 using the batch 
userid and invoking the CMSBATCH command. All jobs submitted for batch 
processing are spooled to the userid of this virtual machine, which 
executes the jobs sequentially. To use the CMS Batch Facility at your 
location, you must ask the system operator the userid of the batch 
virtual machine. 



Submitting Jobs to the CMS Batch Facility 

Under a real OS or DOS system, jobs submitted in batch mode are 
controlled by JCL specifications. Batch jobs submitted to the CMS Batch 
Facility are controlled by the control cards /JOB, /SET, and /*, and by 
CMS commands. 

Any application or development program written in a language 
supported by VM/370 may be executed on the batch facility virtual 
machine. However, there are restrictions on programs using certain CP 
and CMS commands, as described later in this section. 



INPUT TO THE BATCH MACHINE 

Input records must be in card-image format, and may be punched on real 
cards, placed in a CMS file with fixed-length, 80-character records, or 
punched to your virtual card punch. These jots are sent to the batch 
virtual machine in one of two ways: 

• By reading the real punched card input into the system card reader. 

• By spooling your virtual card punch to the virtual reader of the 
batch virtual machine. 

When you submit a real card deck to the batch machine, the first card 
in the deck must be a CP ID card. The ID card takes the form: 



| ID userid I 

where ID must begin in card column one and be separated from userid (the 
batch facility virtual machine userid) by one or more blanks. 
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For example, if your .installation's batch virtual machine has a 
userid of BATCH 1, you punch the card: 

ID BATCH1 

and place it in front of your deck. 

When you are going to submit a job using your virtual card punch, you 
Must first be sure that your punch is spooled to the virtual reader of 
the batch virtual machine: 

cp spool punch to batchl 



liukBlttinj liltual Card Irrput to the CMS Batch Facility 

Virtual card input can be spooled to the batch machine in several ways. 
You may create a CMS file that contains the input control cards and use 
the CMS PUNCH command to punch the virtual cards: 

punch batch jcl (noheader 

When you punch a file this way, you must use the NOHEADER option of the 
PUNCH command, since the CMS Batch Facility cannot interpret the header 
card that is usually produced by the PUNCH command. As it does with 
cards in an invalid format, the batch virtual machine would flush the 
header card. 

You can use an EXEC procedure to submit input to the batch machine. 
From an EXEC, you can punch one line at a time into your virtual punch, 
using the &PUNCH and &BEGPUNCH EXEC control statements. When you do 
this, you must remember to use the CP CLOSE command to release the spool 
punch file when you are finished: 

CP CLOSE PUNCH 

If you are using the EXEC to punch individual lines and entire CMS files 
to be read by the batch virtual machine as one continuous job stream, 
you must remember to spool your punch accordingly: 

CP SPOOL PUNCH CONT 
&PUNCH /JOB BOSWELL 999888 
PUNCH BATCH JCL * (NOHEADER 
CP SPOOL PUNCH NOCONT 
CP CLOSE PUNCH 



I^e /JOB and /* Cards 

A /JOB card must precede each job to be executed under the batch 
facility. It identifies your userid to the batch virtual machine and 
provides accounting information for the system. It takes the form: 

| /JOB userid accntnum [jobname] [comments] I 

l : , .j 
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where; 

userid is your user identification, or the userid under which you 
want the job submitted. This parameter controls: (1) The 
userid charged by the CP accounting routines for the system 
resources used during a job. (2) The name and distribution 
code that appear on any spooled printer or punch output. (3) 
The userid to whom status messages are sent while the batch 
machine is executing the job. 

accntnum is your account number. This account number appears in the 

accounting data generated at the end of your job. It 

overrides the account number in the CP directory entry for the 
userid specified for this job. 

jobname is an optional parameter that specifies the name of the job 
being run. If you specify a jobname, it appears as the in the 
CP spool file identification in the filetype field. The 
filename field always contains CMSBATCH. See "Batch Facility 
Output" below. 

comments may be any additional information you want to provide. 

The /* card indicates the end of a job to the batch facility. It 
takes the form: 



I /* 

i 



The batch facility treats all /* cards after the first as null 
cards. Therefore, if you want to ensure against the previous jcb not 
having a /* end-of-job indicator, you should precede your /JOB card with 
a /* card. 

The /* card is also treated as an end-of-file indicator when a file 
is being read from the input stream. This is a special technigue used in 
submitting source or data files through the card reader, and is 
discussed under "A Batch EXEC for Non-CMS Users." 



The /SET Card 

The /SET card sets limits on a system's time, printing, and punching 
resources during the execution of a job. It takes the form: 



I /SET [TIME seconds] [PRINT lines] [PUNCH cards] 



w h er e : 

seconds is a decimal value that specifies the maximum number of 
seconds of virtual CPU time a job can use. 

lines is a decimal value that specifies the maximum number of lines 
a job can print. 

cards is a decimal number that specifies the maximum number of cards 
a job can punch. 
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The default values for the batch facility are set at 32,767 seconds, 
printed lines, and punched cards per job. Any new limits defined using 
the /SET card must be less than these maximum settings. The system 
resources can be set at lesser values than the default values by an 
installation's system programmer; be sure you know the maximum 
installation values for batch resource limits before you use the /SET 
card. 



HOW THE BATCH FACILITY WORKS 

The CMS Batch Facility, once initialized, runs continuously. When it 
begins executing a job, it sends a message to the userid of the user 
submitting the job. so, if you are logged on when the batch machine 
begins executing a job you sent it, you receive the message: 

MSG FROM BATCHID: JOB 'yourjob' STARTED 

When the batch machine finishes processing a job, it sends the message: 

MSG FROM BATCHID: JOB 'yourjob' ENDED 

where yourjob is the jobname you specified on the /JOB card. Before it 
reads the next job from its card reader, the batch virtual machine: 

« Closes all spooling devices and releases spool files. 

<» Resets any spooling devices identified by the CP TAG command. 

» Detaches any disk devices that were accessed. 

<» Punches accounting information to the system. 

• Reloads CMS. 

All of this "housekeeping" is done by the CMS Batch Facility so that 
each job that is executed is unaffected by any previous jobs. 

If a job that you send to the batch virtual machine terminates 
abnormally (abends), the batch machine sends you a message: 

MSG FROM BATCHID: JOB 'yourjob 1 ABEND 

and spools a CP storage dump of your virtual machine to the printer. 
The remainder of your job is flushed. 

Whenever the batch virtual machine has read and executed all of the 
jobs in its card reader, it waits for more input. 



Preparing Jobs for Batch Execution 

When you want to submit a job to the CMS Batch Facility for execution, 
you should provide the same CMS and CP commands you would use to prepare 
to execute the same job in your own virtual machine. 

You must provide the batch virtual machine with read access to any 
disk input files that are reguired for the job. You do this by supplying 
the LINK and ACCESS command lines necessary. The batch virtual machine 
has an A-disk (195), so you can enter commands to access your disks as 
read-only extensions. For example, if you wanted the batch machine to 
execute a program module named LONDON on your 291 disk, your input file 
might contain the following: 
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/JOB FISH 012345 

CP LINK BOSWELL 291 291 RR SECRET 

ACCESS 291 B/A 

LONDON 

Similarly, if you are using the batch virtual machine to execute a 
program using input and output files, you must supply the file 
definitions: 

CP LINK ARDEN 391 391 RR FOREST 

ACCESS 391 B/A 

FILEDEF INFILE D VITAL STAT 

FILEDEF OUTFILE PUNCH 

CP SPOOL PUNCH TO BOSWELL 

LONDON 

If you expect printed or punched output from your job, you may need 
to include the spooling commands necessary to control the output. In 
the above example, the batch machined punch is spooled to userid 
BOSWELL»s virtual reader. 

Any output printer files produced by your job are spooled by the 
batch virtual machine to the printer. These files are spooled under your 
userid and with the distribution code associated with your userid. You 
can change the characteristics of these output files with the CP SPOOL 
command: 

CP SPOOL E CLASS T 

If you want output to appear under a name other than your userid, use 
the FOR operand of the SPOOL command: 

CP SPOOL E FOR JONSON 

Output punch files are spooled, by default, to the real system card 
punch (under your userid) , unless you issue a SPOOL command in the batch 
job to control the virtual card punch of the batch virtual machine. 

RESTRICTIONS ON CP AND CMS COMMANDS IN BATCH JOBS 

The batch facility permits the use of many CP and most CMS commands. 
The following CP commands can be used to control the batch virtual 
machine: 



CHANGE* 


MSG 


CLOSE* 


QUERY 


DETACH2 


REWIND 


DUMP 


SPOOL 1 


DISPLAY 


STORE 


LINK 3 


TAG 



Not es : 

1. These commands may not be used to affect the virtual card reader. 

2. You can not use this command to detach any spooling devices or the 
system or IPL disks. 

3. The LINK command must be entered on one line in the format 

CP LINK userid vaddr vaddr mode password 

None of the LINK command keywords (AS, PASS, TO) are accepted. If 
the disk has no password associated with it, you must enter the 
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password as ALL. A maximum of 10 links may te in effect at any one 
time. 

All CP commands in a batch job must be prefaced with the "CP" 
command. 

Since the batch virtual machine reads input from its card reader, you 
can not use the following commands or operands that affect the card 
reader: 

ASSGN SYSxxx READER (CMS/DOS only) 
DISK LOAD 
FILEDEF READER 
BEADCABD 

Invalid SET command operands are: 

BLIP OUTPUT 

EMSG REDTYPE 

IMPCP BELPAGE 

INPUT PROTECT 

All the other operands of the SET command can be used in a job executing 
in the batch virtual machine. 



BATCH FACILITY OUTPUT 

Any files that you request to have printed during your job*s execution 
are spooled to the real system printer under your userid, unless you 
have spooled it otherwise. Once released for processing, these output 
files are under the control of the CP spooling facilities; if you are 
logged on, you can control the disposition of these files before they 
are printed with the CLOSE, PURGE, ORDER, and CHANGE commands. 

Output files produced by the batch virtual machine are identifiable 
by the filename CMSBATCH in the CP spool file name field. The spool file 
type field contains the filetype JOB, unless you specified a jobname on 
the /JOB card. This applies to both printer and punch output files. 

In addition to your regular printed output, the CMS Eatch Facility 
spools a console sheet that contains a record of all the lines read in, 
and the responses, error messages, and return codes that resulted from 
command or program execution. This file is identified by a spool file 
name of BATCH and a spool file type of CONSOLE. 



Using EXEC Files for Input to the Batch Facility 

There are a variety of ways that EXEC procedures can help facilitate the 
submission of jobs to the CMS Batch Facility. You can prepare an EXEC 
file that contains all of the CMS commands you want to execute, and then 
pass the name of the EXEC to the batch virtual machine. For example, 
consider the files COPY JCL and COPYF EXEC: 

COPY JCL: /JOB CABBON 999999 
EXEC COPYF 
/* 

COPYF EXEC: COPYFILE FIRST FILE A SECOND = = 
COPYFILE THIRD FILE A FOURTH = = 

236 IBM VM/370: CMS User's Guide 



Then, if you enter the commands 

cp spool punch to cmsbatch 
punch copy jcl * (noheader 

the commands in the EXEC file are executed by the batch virtual 
machine. 

You could also use an EXEC to punch input to the batch virtual 
machine. Using the same commands as in the example above, you might 
have an EXEC named BATCOEY: 

CP SPOOL PUNCH TO BATCH3 

6PUNCH /JOB CARBON 999999 

SPUNCH COPYFILE FIRST FILE A SECOND = = 

SPUNCH COPYFILE THIRD FILE A FOURTH = = 

SPUNCH /* 

CP CLOSE PUNCH 

Then, when you enter the EXEC name: 

batcopy 

The input lines are punched to the batch virtual machine. 

The examples above are very simple; you probably would not go to the 
trouble of sending such a job to the batch virtual machine for 
processing. The examples do, however, illustrate the two basic ways 
that you can use EXEC procedures with the batch facility: 

1 . Invoking an EXEC procedure from a batch virtual machine. 

2. Using an EXEC procedure to create a job stream for the batch 
virtual machine. 

In either case, the EXECs that you use may be very simple or very 
complicated. In the first instance, an EXEC might contain many steps, 
with control statements to conditionally control execution, error 
routines, and so on. 

In the second instance, you might have an EXEC that is versatile, so 
that it can be invoked with different arguments so as to satisfy more 
than one situation. For example, if you want to create a simple EXEC to 
send jobs to the batch virtual machine to be assembled, it might 
contain: 

/JOB ARIEL 888888 

CP LINK ARIEL 191 391 RR LINKPASS 

ACCESS 291 B/A 

ASSEMBLE S1 (PRINT 

CP SPOOL PUNCH TO ARIEL 

PUNCH S1 TEXT A (NOHEADER 

/* 

If this file were named BATCHASM EXEC, then whenever you wanted the CMS 
Batch Facility to assemble a source file for you, you would enter 

batchasm filename 

and the batch virtual machine would assemble the source file, print the 
listing, and send you a copy of the resulting TEXT file. 



Section 12. Using the CMS Batch Facility 237 



SAMPLE SYSTEM PROCEDURES FOR BATCH EXECUTION 

To extend the above example a little further, suppose you wanted to 
process source files in languages other than the assembler language. You 
want, also, for any user to be able to use this EXEC. You might have a 
separate EXEC file for each language, and an EXEC to control the 
submission of the job. This example shows the controlling EXEC file 
BATCH and the ASSEMBLE EXEC. 

BATCH EXEC: 

* THIS EXEC SUBMITS ASSEMBLIES/COMPILATIONS TO CMS BATCH 
* 

* - PUNCH BATCH JOB CARD; 

* - CALL APPROPRIATE LANGUAGE EXEC (£3) TO PUNCH EXECUTAELE COMMANDS 
* 

&CONTROL ERROR 

5IF 8IHDEX GT 2 &SKIP 2 

&TYPE CORRECT FORM IS: BATCH USERID FNAME FTYPE (LANGUAGE) 

&EXIT 100 

&ERROR &GOTO -ERR 1 

CP SPOOL D CONT TO BATCHCMS 

GPUNCH /JOB &1 1111 &2 

SPUNCH CP LINK S1 191 291 RR SECRET 

&PUNCH ACCESS 291 B/A 

EXEC 83 62 81 

&PUNCH /* 

CP SPOOL D NOCONT 

CP CLOSE D 

CP SPOOL D OFF 

&EXIT 

-ERR1 8EXIT 100 

ASSEMBLE EXEC: 

* CORRECT FORM IS: ASSEMBLE FNAME USERID 
* 

* PUNCH COMMANDS TO: 

* - INVOKE CMS ASSEMBLER 

* - RETURN TEXT DECK TO CALLER 
* 

&CONTRCL ERROR 

&ERROR &GOTO -ERR2 

SPUNCH GLOBAL MACLIE UPLIB CMSLIB OSMACRO 

&PUNCH CP MSG 82 ASMBLING « 81 ' 

&PUNCH ASSEMBLE 81 (PRINT NOTERM) 

&PUNCH CP MSG 82 ASSEMBLY DONE 

SPUNCH CP SPOOL D TO 82 NOCONT 

&PUNCH PUNCH 81 TEXT A1 (NOHEADER) 

&BEGPUHCH 

CP CLOSE D 

CP SPOOL D OFF 

RELEASE 291 

CP DETACH 291 

SEND 

SEXIT 

-ERR2 &EXIT 102 
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Executing the Sample EXEC Procedure 

If the above EXEC procedure is invoked with the line: 

batch fay payroll assemble 

The BATCHCMS virtual machined card reader should contain the following 
statements (in the same general form as a FIFO console stack) : 

/JOB FAY 1111 PAYROLL 

CP LINK FAY 191 291 RR SECRET 

ACCESS 291 B/B 

GLOBAL MACLIB UPLIB CMSLIB OSMACRO 

CP MSG FAY ASMBLING • PAYROLL • 

ASSEMBLE PAYROLL (PRINT NOTERM) 

CP MSG FAY ASSEMBLY DONE 

CP SPOOL D TO FAY NOCONT 

PUNCH PAYROLL TEXT A1 (NOHEADER) 

CP CLOSE D 

CP SPOOL D OFF 

RELEASE 291 

CP DETACH 291 

/* 

When the batch facility executes this job, the commands are executed as 
you see them: if you are logged on, you receive, in addition to the 
normal messages that the batch facility issues, those messages that are 
included in the EXEC. 



A BATCH EXEC FOR A NON-CMS USER 

Many installations run the CMS Batch Facility for non-CMS users to 
submit particular types of jobs. Usually, a series of EXEC files are 
stored on the system disk so that each user only needs include a card to 
invoke the EXEC, which executes the correct CMS commands to process data 
included with the job stream. 

For example, if a non-CMS user wanted to compile FORTRAN source 
files, the following BATFORT EXEC file could be stored on the system 
disk: 

8C0NTR0L OFF 

FILEDEF INMOVE TERM (RECFM F BLOCK 80 LRECL 80 

FILEDEF OUTMOVE DISK 81 FORTRAN A1 (RECFM F LRECL 80 BLOCK 80 

MOVEFILE IN OUT 

GLOBAL TXTLIB FORTRAN 

FORTGI £1 (PRINT) 

&F0RTRET = SRETCODE 

SIF SRETCODE NE &GOTO -EXIT 

PUNCH S1 TEXT A1 (NOHEADER) 

-EXIT 8EXIT &F0RTRET 

To use this EXEC, a non-CMS user might place the following real card 
deck in the system card reader : 
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ID CMSBATCH 

/JOB JOEUSER 1234 JOB 1 

BATFORT JOEFORT 

source file 

/* (end-of-file indicator) 
/* (end-of-job indicator) 

When the batch virtual machine executes this job, it begins reading 
the EXEC procedure from disk, and executes one line at a time. When it 
encounters the MOVEFILE command, it begins reading the source file from 
its card reader (the batch facility interprets a terminal read as a 
request to read from the card reader) . It continues reading until it 
reaches the end-of-file indicator (the /* card) , and then resumes 
processing the EXEC on the next line following the MOVEFILE command 
line. 

Additional functions may be added to this EXEC procedure, or others 
may be written and stored on the system disk to provide, for example, a 
compile, load, and execute facility. These EXEC procedures would allow 
an installation to accommodate the non-CMS users and maintain common 
user procedures. 
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Section 13. Programming for the CMS Environment 



This section contains information for assembler language programmers who 
may occasionally need to write programs to be used in the CMS 
environment. The conventions described here apply only to CMS virtual 
machines; you can not execute these programs under any other operating 
systems. 



Program Linkage 

Program linkages, in CMS, are generally made fcy means of a supervisor 
call instruction, SVC 202. The SVC handling routine takes care of 
program linkage for you. The registers used, and their contents, are 
discussed in the following paragraphs. 

Ke^ister J: Points to a parameter list of successive doublewords. The 
first entry in the list is the name of the called routine or program, 
and any successive doublewords may contain arguments passed to the 
program. Parameter lists are discussed under "Parameter Lists." 

Maister 1,3: Contains the address of a 24-fullword save area, which you 

can use to save your caller's registers. This save area is provided to 

satisfy standard OS and DOS linkage conventions; you do not need to use 
it in CMS, since the SVC routines save the registers. 

l®3i§ter Ji* : Contains the return address of the SVC handling routines. 
You must return control to this address when you exit from your 
program. 

The CMS routines that get control by way of register 14 close files, 
update your disk file directory, and calculate and type the time used in 
program execution. These values appear in the CMS Ready message, which 
is displayed at your terminal when your program finishes execution: 

B;T=n.nn/x. xx hh:mm:ss 

where n.nn is the CMS CPU time (in seconds) and x.xx is the combined CP 
and CMS CP time. hh:.mm:ss is the time of day in hours, minutes, and 
seconds. 

ISSister J5: Contains your program's entry point address. You can use 
this address to establish immediate addressability in your program. You 
should not use it as a base address, however, since all CMS SVCs use it 
for communication with your programs. 

Figure 20 shows a sample CMS assembler language program entry and exit. 
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PROGRAM CSECT 

USING PROGRAM, 12 

LR 12,15 

ST 14, SAVRET 



ESTABLISH ADDRESSABILITY 
SAVE RETURN ADDRESS IN R14 





L 


14, SAVRET 


LOAD RETURN ADDRESS 




LA 


15,0 


SET RETURN CODE IN R15 




BR 


14 


GO 


SAVRET 


DS 


F 


SAVE AREA 



Figure 20. Sample CMS Assembler Program Entry and Exit Linkage 



RETURN CODE HANDLING 



Register 15, in addition to its role in entry linkage, is also used, in 
CMS, as a return code register. All of the CMS internal routines pass a 
completion code by way of register 15, and the SVC routines that receive 
control when any program completes execution examine register 15. 



If register 15 contains a nonzero value, 
CMS Ready message, following the "R": 

R (nnnnn) ;T=n.nn/x.xx hh:mm:ss 



this value is placed in the 



It is good practice, when you are executing programs in CMS, if your 
programs do not use register 15 as a return code register, to place a 
zero in it before transferring control back to CMS. Otherwise, the Ready 
message may display meaningless data. 



PARAMETER LISTS 



When you execute a program from your terminal, a CMS scan roatine sets 
up a parameter list based on your command input line. The parameter list 
is doubleword aligned, with parameters occupying successive doublewords. 
The scan routine recognizes blanks and parentheses as argument 
delimiters; parentheses are placed, in the parameter list, in separate 
doublewords. 

For example, if you have a CMS MODULE file named TESTPROG, and you 
call it with the command line: 

testprog (file2) 

The scan routine sets up the parameter list: 



CMNDLIST DS 


0D 


DC 


CL8'TESTPROG« 


DC 


CL8 1 (• 


DC 


CL8 I FILE2 I 


DC 


CL8«) • 


DC 


8X«FF» 



The last doubleword is made up of all 1s, to act as a delimiter. 

If you enter any argument longer than 8 characters, it is truncated 
and only the first 8 characters appear in the list. However, no error 
condition results. 
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Usina Parameter Lists 

The scan routine that sets up this parameter list places the address of 
the list in register 1, and then calls the SVC handling routine. The 
SVC routine gives control to the program named in the first doubleword 
of the parameter list. 

When your program receives control, it can examine the argument list 
passed to it by way of register 1. 

You can use this technique, also, to call CMS commands from your 
programs. 

When you use the LOAD and RUN commands to execute a program in CMS, 
you can pass an argument list to the program on the command line. For 
example, if you enter 

load myprog 

start * runl proga 

the arguments RUH1 and PROGA are placed in a parameter list and register 
1 contains the address of this list when your program receives control. 
If you want to use the RUN command to perform the load and start 
functions, you could enter 

run myprog (runl proga 

The parenthesis indicates the beginning of the argument list. 



Calling a CMS Command from a Program 

You can call a CMS command from a program by setting up a parameter 
list, like that shown above, and then issuing an SVC 202. The parameter 
list you set up must have doublewords that contain the parameters or 
arguments you would enter if you were entering the command from the 
terminal. For example: 

PUNCHER DS 0D 

DC CL8»PUNCH» 

DC CL8'NAME' 

DC CL8'TYPE» 

DC CL8 1 *' 

DC CL8 1 (• 

DC CL8«NOH» 

DC SX'FF 1 

In your program, when you want to execute this command, you should load 
the address of the list into register 1 , and issue the supervisor call 
instruction (SVC) as follows: 

LA 1, PUNCHER 

SVC 202 

DC ALU (ERROR) 

When you issue an SVC 202, you must supply an error return address in 
the four bytes immediately after the SVC instruction. If the return code 
(register 15) contains a nonzero value after returning from the SVC 
call, control passes to the address specified. In the above example, 
control would go pass to the instruction at the label ERROR. 
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If you want to ignore errors, you can use the sequence: 

LA 1, PUNCHER 

SVC 202 

DC ALU (*+4) 

If you do not specify an error address, control is returned to the next 
instruction after a normal return, but if there was an error executing 
the CNS command, your program terminates execution. 

If you want to execute a CF command or an EXEC procedure from a 
program, you must use the CP and EXEC commands; for example 

SPOOL 



DS 


0D 


DC 


CL8'CP» 


DC 


CL8 'SPOOL' 


DC 


CL8'PRINTER» 


DC 


CL8' CLASS' 


DC 


8X'FF' 


DC 


CL8'EXEC 


DC 


CL8'PFSET« 


DC 


SX'FF' 



EXEC 



As an alternative, you can use the CMS LINEDIT macro to call a CP 
command from a program. Specify DISP=CPCOMM on the macro instruction, 
for example 

LINEDIT TEXT'SPOOL E CLASS S • , DISP=CPCOMM ,DOT=NO 

The LINEDIT macro is described in VM^370: CMS Command and Macro 
Reference. 



Executing Program Modules 

MODULE files, in CMS, are nonrelocatable programs. Using the GENMOD 
command, you can create a module from any program that uses OS or CMS 
macros. When you create a module, it is generated at the virtual 
storage address at which it is loaded, for example: 

load myprog 
genmod testit 

The CMS disk file, TESTIT MODULE A, that is created as a result of this 
GENMOD command, always begins execution at location X'20000 1 , the 
beginning of the user program area. 

If you want to call your own program modules using SVC 202 
instructions, you must be careful not to execute a module that uses the 
same area of storage that your program occupies. If you want to call a 
module that executes at location X'20000', you can load the calling 
program at a higher location, for example, 

load myprog (origin 30000 

As long as the MODULE file called by MYPROG is no longer than X' 10000' 
bytes, it will not overlay your program. 

Many CMS disk-resident command modules also execute in the user 
program area; if you call these commands from a program, you should load 
your program at a higher location. 



!44 IBM VM/370: CMS User's Guide 



THE TRANSIENT PROGRAM AREA 

To avoid overlaying programs executing in the user program area, you can 
generate program modules to run in the CMS transient area, which is a 
2-page area of storage that is reserved for the execution of programs 
that are called for execution freguently. Many CMS commands run in this 
area, which is located at X'EOOO*. To generate a module to run in the 
transient area, use the ORIGIN TRANS option when you load the TEXT file 
into storage, then issue the GENMOD command: 

load myprog (origin trans 
genmod setup (str 

You should use the STR option of the GENMOD command so that when the 
module is loaded into the transient area, storage remaining from 
previously executed programs is cleared. 

The two restrictions placed on command modules executing in the 
transient area are: 

1. They may have a maximum size of 8192 bytes, since that is the size 
of the transient area. This size includes any free storage acguired 
by GETMAIN macros. 

2. They must be serially reusable. When a program is called by an SVC 
202, if it has already been loaded into the transient area, it is 
not reloaded. 

The CMS commands that execute in the transient area are: ACCESS, 
ASSGM, COMPARE, DISK, DLBL, FILEDEF, GENDIRT, GLOBAL, LISTFILE, MODMAP, 
OPTION, PRINT, PUNCH, QUERY, READCARD, RELEASE, RENAME, SET, SVCTRACE, 
SYNOHYM, TAPE, and TYPE. 



CMS Macro Instructions 

There are a number of assembler language macros distributed with the CMS 
system that you can use when you are writing programs to execute in the 
CMS environment. They are in the macro library CMSLIB MACLIB, which is 
normally located on the system disk. There are macros to manipulate CMS 
disk files, to handle terminal communications, to manipulate unit record 
and tape input/output, and to trap interrupts. These macros are 
discussed in general terms here; for complete format descriptions, see 
Ii!Z370: CMS Command and Macro Reference. 



MACROS FOR DISK FILE MANIPULATION 

Disk files are described in CMS by means of a file system control block 
(FSCB) . The CMS macro instructions that manipulate disk files use FSCBs 
to identify and describe the files. When you want to manipulate a CMS 
file, you can refer to the file either by its file identifier, 
specifying •filename filetype filemode* in guotation marks, or you can 
refer to the FSCB for the file, specifying FSCB=fscb, where fscb is the 
label on an FSCB macro. 

To establish an FSCB for a file, you can use the FSCB macro 
specifying a file identifier, for example: 

INFILE FSCB 'INPUT TEST A1 • 
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You can also provide, on the FSCB macro, descriptive information to be 
used by the input and output macros. If you do not code an FSCB macro 
for a file, an FSCB is created inline (following the macro instruction) 
when you code an FSREAD, FSHRITE, or FSOPEN macro. 



The format of an 
each of the fields. 



FSCE is listed below, followed by a description of 



Label 






FSCBCOMM 


DC 


CL8" • 


FSCBFN 


DC 


CL8' » 


FSCBFT 


DC 


CL8" ■ 


FSCBFM 


DC 


CL2» ' 


FSCBITHO 


DC 


H«0» 


FSCBBUFF 


DC 


A«0» 


FSCBSIZE 


DC 


F'O" 


FSCBFV 


DC 


CL2*F» 


FSCBNOIT 


DC 


H" 1« 


FSCBNORD 


DC 


AL4(0) 



2§scri£tion 

File system command 

Filename 

Filetype 

Filemode 

Relative record number (RECNO) 

Address of buffer (BUFFER) 

Number of bytes to read or write (BSIZE) 

Record format - F or V (RECFM) 

Number of records to read or write (NOREC) 

Number of bytes actually read 

The labels shown above are not generated by the FSCB macro; to reference 
fields within the FSCB by these labels, you must use the FSCBD macro to 
generate a DSECT. 

FSCBCOMM: When the FSCBFN, FSCBFT, and FSCBFM fields are filled in, you 
can fill in the FSCBCOMM field with the name of a CMS command, and use 
the FSCB as a parameter list for an SVC 202 instruction. (You must 
place a delimiter to mark the end of the command line.) 

I§CBFN, FSCBFT, FSCBFM; The filename, filetype and filemode fields 
identify the CMS file to be read or written. You can code the fileid on 
a macro line in the format •filename filetype filemode' or you can use 
register notation. If you use register notation, the register that you 
specify must point to an 1 8-byte field in the format: 



FILEID 


DC 


CL8»filename' 




DC 


CL8» filetype' 




DC 


CL2»fm« 



The fileid must be specified either in the FSCB for a file or on the 
FSREAD, FSHRITE, FSOPEN, or FSERASE macro you use that references the 
file. 

FS CBITNO : The record, or item number indicates the relative record 
number of the next record to be read or written; it can be changed with 
the RECNO option. The default value for this field is 0. When you are 
reading files, a indicates that records are to be read sequentially, 
beginning with the first record in the file. When you are writing 
files, a indicates that records are to fce written seguentially, 
beginning at the first record following the end of the file, if the file 
already exists, or with record 1, if it is a new file. 

FSCBBUFF: The buffer address, specified in the BUFFER option, indicates 
the label of the buffer from which the record is to be written, or into 
which the record is to be read. You should always supply a buffer large 
enough to accommodate the longest record you expect to read or write,. 
This field must be specified, either in the FSCB, or on the FSREAD or 
FSHRITE macro. 

FSCBSIZE: This field indicates the number of bytes that are read or 
written with each read or write operation. The default value is 0. If 
the buffer that you use represents the full length of the records you 
are going to be reading or writing, you can use the BSIZE option to set 
this field equal to your buffer length. This field must be specified. 
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FSCBFV: This 2-character field indicates the record format (RECFM) of 
the file. The default value is F (fixed). 

FSCBNOIT: This field contains the number of whole records that are to be 

read or written in each read or write operation. You can use the NOREC 

option in conjunction with the BSIZE option, to block and deblock 
records. The default Value is 1. 

FSCBMORD: Following a read operation, this field contains the number of 
bytes that were actually read, so that if you are reading a 
variable-length file, you can determine the size of the last record 
read. The FSREAD macro places the information from this field into 
register 0. 



Using, the FSCB 

The following example shows how you might code an FSCB macro to define 
various file and buffer characteristics, and then use the same FSCB to 
refer to different files: 

FSREAD 'INPUT FILE A 1 • , FSCB=COMMON 
FSWRITE 'OUTPUT FILE A1 ' ,FSCB=COMMCN 



COMMON FSCB BUFFER=SHARE ,RECFM=V,BSI ZE=200 
SHARE DS CL200 

In the above example, the fileid specifications on the FSREAD and 
FSWRITE macros modify the FSCB at the label COMMON each time a read or 
write operation is performed, you can also modify an FSCB directly by 
referring to fields by a displacement off the beginning of the FSCB, for 
example, 

MVC FSCB+S^CLe'NEWNAME' 

moves the name NEHNAME into the filename field of the FSCB at the label 
FSCBFN. 

As an alternative, you can use the FSCBD macro to generate a DSECT, 
and refer to the labels in the DSECT to modify the FSCB, for example: 

LA R5,INFSCB 
USING FSCBD, R5 

MVC FSCBFN, NEHNAME 

INFSCB FSCB "INPUT TEST A1« 
NEWNAME DC CL8'OUTPUT« 
FSCBD 

In the above example, the MVC instruction places the filename OUTPUT 
into the FSCBFN (filename) field of the FSCB. The next time this FSCB is 
referenced, the file OUTPUT TEST is the file that is manipulated. 
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Shading and Writing CHS Disk Files 

CMS disk files are sequential files; when you use CMS macros to read and 
write these files, you can access them sequentially with the FSREAD and 
FSWRITE macros. However, you may also refer to records in a CMS file by 
their relative record numbers, so you can, in effect, access records 
using a direct access method. 

If you know which record you want to read or write, you can specify 
the RECNO option on the FSCB macro, or on the FSOEEN, FSREAD, or FSWRITE 
macros. When you use the RECNO option on the FSCB macro, you must 
specify it as a self-defining term; for the FSOPEN, FSREAD, or FSWRITE 
macros, you may specify either a self-defining term, as: 

WRITE FSWRITE FSCB=WFSCB ,RECNO= 10 
or using register notation, as follows: 

WRITE FSWRITE FSCB=WFSCB, RECNO= (5) 

where register 5 contains the record number of the record to be read. 

When you want to access files sequentially, the FSCBITNO field of the 
FSCB must be 0. This is the default value. When you are reading files 
with the FSREAD macro, reading begins with record number 1. When you 
are writing records to an existing file with the FSWRITE macro, writing 
begins following the last record in the file. 

To begin reading or writing files sequentially beginning at a 
specific record number, you must specify the RECNO option twice: once to 
specify the relative record number at which you want to begin reading, 
and a second time to specify RECNO=0 so that reading or writing will 
continue sequentially beginning after the record just read or written. 
You can specify the RECNO option on the FSREAD or FSWRITE macro, cr you 
■ay change the FSCBITNO field in the FSCB for the file. 

For example, to read the first record and then the 50th record of a 
file, you could code the following: 

READ1 FSREAD FSCB=RFSCE 

FSWRITE FSCB=WFSCB 

LA 5,RFSCB 

USING FSCBD,5 

MVC FSCBITNO, =H» 50' 
READ50 FSREAD FSCB=RFSCB 

FSWRITE FSCB=WFSCB 



RFSCB FSCB • INPUT FILE A 1 • , BUFFER = COMMON 

WFSCB FSCB 'OUTPUT FILE A1 • ,BUFFER=C0MMCN ,BSIZE= 120 

COMMON DS CL120 



FSCBD 

In this example, the statements at the label READ1 write record 1 from 
the file INPUT FILE A1 to the file OUTPUT FILE A1. Then, using the 
DSECT generated by the FSCBD macro, the FSCBITNO field is changed, and 
record 50 is read from the input file and written into the output file. 
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If you want to read and write records from the same file, you oust 
issue an FSCLOSE macro to close the file whenever you switch from 
reading to writing. For example: 

LA 3,2 
READ FSREAD FSCB=UPDATE,RECNO= (3) ,ERROR=READERR 
FSCLOSE FSCB=*UPDATI 



FSWRITE FSCB=*UPDATE,RECN0=(3) , ERROR=WRITERR 
FSCLOSE FSCB=UPDATE 
LA 3,1(3) 
B READ 



UPDATE 



FSCB 'UPDATE FILE A1 • ,BUFFER=BUF1 ,BSIZE=80 



To execute a loop to read, update, and rewrite records, you must read 
a record, close the file, write a record, close the file, and so on. 
Since closing a file repositions the read pointer to the beginning of 
the file and the write pointer at the end of the file, you must specify 
the relative record number (RECNO) for each read and write operation. In 
the above example, register 3 is used to contain the relative record 
number. It is initialized to begin reading with the second record in 
the file and is incremented by 1 following each write operation. 



QESfill!!! 55J Closincj Files 



The example above illustrated one of the situations in which you must 
explicitly close a file with the FSCLOSE macro. Usually, CHS opens a 
file whenever an FSREAD or FSWRITE macro is issued for the file. Hhen 
control returns to CHS from a calling program, all open files are closed 
by CHS, so you do not have to close files at the end of a program. 

If, however, you use an EXEC to execute a program to read or write a 
file, the file is not closed by CHS until the EXEC completes execution. 
Therefore, if you read or write the same file more than once during the 
EXEC procedure, you must use an FSCLOSE macro to close the file after 
using it in each program, or use the FSOPEN macro to open it before each 
use. Otherwise, the read or write pointer is positioned as it was when 
the previous program completed execution. 

CREATING NEJ I IkM§. • When you want to begin writing a new file using CHS 
data management macros, there are two ways to ensure that the file you 
want to create does not already exist. One way is to issue the FSSTATE 
macro to verify the existence of the file. 

A second way to ensure that a file does not already exist is to issue 
an FSERASE macro to erase the file. If the file does not exist, register 
15 returns with a code of 28. If the file does exist, it is erased. 

Figure 21 illustrates a sample program using CHS data management 
macros. 
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LINE SOURCE STATEMENT 

BEGIN CSECT Q 
PRINT NOGEN 

USING *,12 ESTABLISH ADDRESSABILITY 

LR 12,15 

ST 14, SAVE ^ 

LA 2,8(,1) R2=ADDR OF INPUT FILEID IN PLIST A 
LA 3,32 (,1) R3=ADDR OF OUTPUT FILEID IN PLIST 

* DETERMINE IF INPUT FILE EXISTS 

FSSTATE (2) ,ERROR=ERR1 
* 

* READ A RECORD FROM INPUT FILE AND WRITE ON OUTPUT FILE 
RD FSREAD (2) ,ERROR=EOF ,BUFFER=BUFF1 , BSIZE=80 A 

FSWRITE (3) ,ERBOR=ERR2,BUFFER=BUFF1,BSIZE=80 ^^ 
B RD LOOP BACK FOR NEXT RECORD 

* 

* COME HERE IF ERROB READING INPUT FILE 

EOF C 15, = FM2' END OF FILE ? A 
BNE ERR3 ERROR IF NOT 

LA 15,0 ALL O.K. - ZERO OUT R15 

B EXIT GO EXIT 

* IF INPUT FILE DOES NOT EXIST 

ERR1 WRTERM 'FILE NOT FOUND ■ ,EDIT=YES 

B EXIT 
* 

* IF ERROR WRITING FILE ^^ 
ERR2 LR 10,15 SAVE RET CODE IN REG 10 fj) 

LINEDIT TEXT=' ERROR CODE .... IN WRITING FILE' , SUB= (DEC , (1 0) ) 
B EXIT 
* 

* IF READING ERROR WAS NOT NORMAL END OF FILE j^ 
ERR3 LR 10,15 SAVE RET CODE IN REG 10 %Sf 

LINEDIT TEXT=»ERROR CODE .... IN READING FILE 1 ,SUE= (DEC, ( 10) ) 

LOAD RETURN ADDRESS 
RETURN TO CALLER 



* 






EXIT 


L 


14, SAVE 


At 


BR 


14 


BUFF1 


DS 


CL80 


SAVE 


DS 
END 


F 



Not es : 
^k The program might be invoked with a parameter list in the format 
^^ progname INPUT FILE A1 OUTPUT FILE A1. This line is placed in a 
parameter list by CMS routines and addressed by register 1 

0(see note 2) . 
The parameter list is a series of doublewords, each containing 
one of the words entered on the command line. Thus, 8 bytes 
past register 1 is the beginning of the input f ileid ; 24 bytes 
^^beyond that is the beginning of the second fileid. 
^pThe FSREAD and FSWRITE macros cause the files to be opened; no 

open macro is necessary. CMS routines close all open files when 
_^ a program completes execution. 

^P The return code in register 15 is tested for the value 12, 
which indicates an end— of-file condition. If it is the end of 
the file, the program exits; otherwise, it writes an error 
^^ message. 

^P The dots in the LINEDIT macro are substituted, during execution, 
with the decimal value in register 10. 

Figure 21. A Sample Listing of a Program that Uses CMS Macros 
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CBS MACROS FOR TERMINAL COMMUNICATIONS 

There are four CMS macros you can use to write interactive, 
terminal-oriented programs. They are RDTERM, WRTERM, LINEDIT, and 
WAITT. RDTERM and WRTERM only require a read/write buffer for sending 
and receiving lines from the terminal. The third, LINEDIT, has a 
substitution and translation capability. 

When you use the WRTERM macro to write a line to your terminal you 
can specify the actual text line in the macro instruction, for example: 

DISPLAY WRTERM »GOOD MORNING* 

You can also specify the message text by referring to a buffer that 
contains the message. 

The RDTERM macro accepts a line from the terminal and reads it into a 
buffer you specify. You could use the RDTERM and WRTERM macros together, 
as follows: 



WRITE 


WRTERM 


•ENTER LINE 1 


READ 


RDTERM 


BUFFER 




LR 3, 


,0 


REWRITE 


WRTERM 


BUFFER, (3) 



BUFFER DS CL130 

In this example, the WRTERM macro results in a prompting message. Then 
the RDTERM macro accepts a line from the terminal and places it in the 
buffer BUFFER. The length of the line read, contained in register on 
return from the RDTERM macro, is saved in register 3. When you specify 
a buffer address on the WRTERM macro, you must specify the length of the 
line to be written. Here, register notation is used to indicate that 
the length is contained in register 3. 

The LINEDIT macro converts decimal and hexadecimal data into EBCDIC, 
and places the converted value into a specified field in an output 
line. There are list and execute forms of the macro, which you can use 
in writing reentrant code. Another option allows you to write lines to 
the offline printer. The LINEDIT macro is described, with extensive 
examples, in VM/370: CMS Command and Macro Reference. Figure 21 shows 
how you might use the LINEDIT macro to convert and display CMS return 
codes. 

The WAITT (wait terminal) macro instruction can help you to 
synchronize input and output to the terminal. If you are executing a 
program that reads and writes to the terminal frequently, you may want 
to issue a WAITT macro to halt execution of the program until all 
terminal I/O has completed. 



CMS MACROS FOR UNIT RECORD AND TAPE I/O 

CMS provides macros to simplify reading and punching cards (RDCARD and 
PUNCHC) , and creating printer files (PRINTL) . When you use either the 
PUNCHC or PRINTL macros to write or punch output files while a program 
is executing, you should remember to issue a CLOSE command for your 
virtual printer or punch when you are finished. You can do this either 
after your program returns control to CMS, by entering: 
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cp close e 

-- or -- 

cp close d 

or, you can set up a parameter list with the command line CP CLOSE E or 
CP CLOSE D and issue an SVC 202. 

The tape control macros, RDTAPE, WRTAPE and TAPECTL, can read and 
write CMS files from tape, or control the positioning of a tape. 



INTERRUPT HANDLING MACROS 



You can set up routines in your programs to handle interrupts caused by 
I/O devices, by SVCs, or by external interrupts using the HNDINT, 
HNDSVC, or HNDEXT macro instructions. 

With the HNDINT macro instruction, you can specify addresses that are 
to receive control when an interrupt occurs for a specified device. If 
the WAIT option is used for a device specified in the HNDINT macro, then 
the interrupt handling routine specified for the device does not receive 
control until after the HAITD macro is issued for the device. 

You can use, the HNDSVC macro to trap Supervisor Call instructions of 
particular numbers, if, for example, you want to perform some additional 
function before passing control, or you do not want any SVCs of the 
specified number to be executed. 

The CP EXTERNAL command simulates external interrupts in your virtual 
machine; if you want to be able to pass control to a particular internal 
routine in the event of an external interrupt, you can use the HNDEXT 
macro. 
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Part 3. Learning To Use EXEC 



In previous sections, the CMS EXEC facilities were described in general 
terms to acquaint you with the expressions used in EXEC files and the 
basic way that EXECs function. Also, examples of EXEC procedures have 
appeared throughout this publication. You should be familiar at least 
with the material in "Introduction to the EXEC Processor" before you 
attempt to use the information in Part 3. 

"Section 14. Building EXEC Procedures" describes the EXEC facilities 
in detail, with examples of techniques you may find useful as you learn 
about EXEC and develop your own EXEC procedures. 

Special considerations for using CMS commands in EXECs, and modifying 
CMS command functions using EXEC procedures, are described in "Section 
15. Using EXECs With CMS Commands." 

"Section 16. Refining Your EXEC Procedures" lists several techniques 
you can use to make your EXEC files easier to use, and provides some 
hints on debugging EXEC procedures. 

If you are a frequent user of the CMS Editor, then you may be 
interested in "Section 17. Writing Edit Macros," which describes how to 
create your own EDIT subcommands using EXEC procedures. 
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Section 14. Building EXEC Procedures 



This section discusses various techniques that you can use when you 
write EXEC procedures. The examples are intended only as suggestions: 
you should not feel that they represent either the only way or the best 
way to achieve a particular result. Many combinations and variations of 
control statements are possible; in most cases, there are many ways to 
do the same thing. 

This section is called "Building EXEC Procedures" because you will 
often find that once you have created an EXEC procedure and begun to use 
it, you continually think of new applications or new uses for it. Using 
the CMS Editor, you may guickly build the additions and make the 
necessary changes. You are encouraged to develop EXEC procedures to help 
you in all the phases of your CMS work. 



What is a Token? 

An executable statement is any line in an EXEC file that is processed by 
the EXEC interpreter, including: 

• CMS command lines 

• EXEC control statements 

• Assignment statements 

• Null lines 

Executable statements may appear by themselves on a line, or as the 
object of another executable statement, for example in an SIF or SLOOP 
control statement. If you want to execute CP commands or other EXEC 
procedures in an EXEC, you must use the CP and EXEC commands, 
respectively. CP commands are passed directly to CP for processing. 

All executable statements in an EXEC are scanned by the CMS scan 
routine. This routine converts each word (words are delimited by blanks 
and parentheses) into an 8-character quantity, called a token. If a 
word contains more than 8 characters, it is truncated on the right. If 
it contains fewer than eight characters, it is padded with blanks. When 
a parenthesis appears on the line, it is treated both as a delimiter and 
as a token. For example, the line 

6TYPE WHAT IS YOUR PREFERENCE (RED|BLUE)? 

scans as follows: 

8TYPE WHAT IS YOUR PREFEREN ( RED| BLUE ) ? 

After a line has been scanned, each token is scanned for ampersands, 
and substitutions are performed on any variable symbols in the tokens 
before the statement is executed. 

Nonexecutable statements are lines that are not processed by the EXEC 

interpreter, that is comment lines (those that begin with an *) , and 

data lines following an &BEGEMSG, &BEGPUNCH, 8BEGSTACK, or SBEGTYPE 

control statement. Since these lines are not scanned, words are not 
truncated, and tokens are neither formed nor substituted. 

Since all executable statements in an EXEC are scanned, and the data 
items are treated as tokens, the term "token" is used throughout this 

Section 14. Building EXEC Procedures 255 



section to describe data items before and after scanning. The VM/370: 
CMS Command and Macro Reference, which contains the formats ""and 
descriptions of the EXEC control statements, uses this convention as 
well. Therefore, as you create your EXEC procedures, you may think of 
the items that you enter on an EXEC statement as tokens, since that is 
how they are used by the EXEC interpreter. 



Variables 

To make the best use of the CMS EXEC facilities, you should have an 
understanding of how the EXEC interpreter performs substitutions on 
variable symbols contained in tokens. Some examples follow. For each 
example, the input lines are shown as they would appear in an EXEC file 
and as they would appear after being interpreted and executed by EXEC. 
Notes concerning substitution follow each example. 

SIMPLE SUBSTITUTION: Most of the EXEC examples in this publication 
contain variable symbols that result in one-for-one substitution. Most 
of your variables, too, will have a similar relationship. 

Lines After Substitution 

6X = 123 6X =~123 

6TYPE 6X 6TYPE 123 

The EXEC interpreter accepts the variable symbol &X and assigns it the 
value 123. In the second statement, SX is substituted with this value, 
and the control statement &TYPE is recognized and executed. 

Lines After Substitution 

6Y ="456 6Y =~456 

SZ = 8Y 6Z = 456 

The symbol &Y is assigned a value of 456. In the second statement, the 
symbol &Y is substituted with this value, and this value is assigned to 
6Z. 

SUBSCRIPTS FOR VARIABLES 2 Since each token is scanned more than once for 
ampersands, you can simulate subscripts by using two variable values in 
the same token. 

Lines After Substitution 

S1~=~ ALPHA 81""=' ALPHA 

82 = BETA 82 = BETA 

8INDEX1 = 1 6INDEX1 = 1 

&TYPE &&INDEX1 &TYPE ALPHA 

8INDEX1 = 2 &INDFX1 = 2 

&TYPE 8&INDEX1 &TYPE BETA 

In the statement 8TYPE &8INDEX1, the token &INDEX1 is scanned the first 
time, and the value &INDEX1 is substituted with the value 1. The token 
now contains 81, which is substituted with the value ALPHA on a second 
scan. When the value of &INDEX1 is changed to 2, the value of &&INDEX1 
also changes. 

Lines After Substitution 

81 ="2 81 ="2 , 

8X61 = 5 8X2 = 5 

81 = 1 61 = 1 

8X61 =2 6X1 = 2 

6X = 6X61 + &X6X&I 8X = 2 + 5 
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In the statement 6X61 = 5, analysis of the first token results in the 
substitution of the symbol 61 with the value of 2. The symbol 6X2 is 
assigned a value of 5. 

The value of 61 is changed to 1, and the symbol 6X1 is assigned a 
value of 2. 

In the last statement, 6X =* 6X61 + 6X6X61 , the value of 61 in the 
token 6X61 is replaced with 1, then the symbol 6X1 is substituted with 
its value, which is 2. The token 6X6X61 is substituted after each of 
three scans: 61 is replaced with the value 1, to yield the token 6X6X1. 
The symbol 6X1 has the value of 2, so the token is reduced to 6X2, which 



has a value of 5. 



COMPOUND VARIABLE SYMBOLS: Variable symbols may also be combined with 
character strings. 

iifies After Substitution 

6X""= BEE 6X~=~bIe 

6TYPE H0NEY6X 6TYPE HONEYBEE 

6TYPE ABUMBLE6X 6TYPI ABUMBLE 

In the above example, the first symbol encountered in the scan of 
H0NEY8X is SX, which is substituted with the value 6BEE. In the second 
6TYPE statement, the X is truncated when the line is scanned; the symbol 
6 is an undefined symbol and is therefore set to blanks. 

iia®s After Substitution 

6X = HONEY 6X = HONEY 

6Y = BEE 6Y = BEE 

6TYPE 6X6Y 6TYPE 

In the above example, after the symbol 6Y is substituted with the value 
BEE, the token contains the symbol 6XBEE, which is an undefined symbol, 
so the symbol is discarded. 

Lines After Substitution 

6123~= ABCDE 6123~= ABCDE 

6X = 12345678 6X = 12345678 

6TYPE ABLE66X 6TYPE ABLEABCD 

In this example, the substitution of 6X in the token ABLE66X results in 
the character string ABLE612345678, which is truncated to 8 characters, 
or ABLE6123. The scan continues, and 6123 is substituted with the 
appropriate value, to result in ABCDE. The token is again truncated to 8 
characters. 

SUBSTITUTING LITERAL VALUES: You might want an ampersand to appear in a 
token. You can use the 6LITERAL built-in function to suppress the 
substitution of variable symbols in a token. 

Lines After Substitution 

69 ="HELLO 69 =~HELLO 

6A = 6LITERAL 69 6A = 6LITERAL 69 

6TYPE 6A 6TYPE 69 

Because the value of 6A was defined as a literal 69, no substitution is 
performed. 

|jiS®s After Substitution 

6TYPE = QUERY 6TYP1 = QUERY 

6TYPE BLIP QUERY BLIP 

In the above example, even though 6TYPE is an EXEC keyword, it is 
assigned the value of QUERY, and substitution is performed when it 
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appears on an input line. In this example, when it is substituted with 
its value, the result is a command line which is passed to CMS for 
processing . 

iiS^s J^ter Substitution 

SCONTROL = FIRST SCONTROL = FIRST" 
&LITERAL SCONTROL ALL SCONTROL ALL 

In this example, SCONTROL is assigned a value as a variable symbol, but 
when it is preceded by the built-in function SLITERAL, the substitution 
is not performed, so EXEC processes it as a control statement. 

IIXADECIMAL AND DECIMAL CONVERSIONS: You can perform hexadecimal to 
decimal and decimal to hexadecimal conversions in an EXEC if you use the 
control statement &HEX ON. To convert hexadecimal to decimal, you must 
use an assignment statement, prefacing the hexadecimal value you want to 
convert with the characters X 1 and assigning the value to a variable 
symbol. 

Lillys After Substitution 

SHEX ON SHEX ON 

SDEC = X« 10 SDEC = X« 10 

&TYPE SDEC &TYPE 16 

SCOUNT = 15 &COUNT = 15 

SDECNT = X»SCOUNT SDECNT = X'15 

STYPE SDECNT &TYPE 21 

When the characters X' are found in any EXEC statement other than an 
assignment statement, the value following them is considered a decimal 
value and is converted to its hexadecimal eguivalent. 

IiiBi-s After Substitution 

SHEX OH SHEX ON 

STYPE X«20 STYPE 14 

&VAL = 3000 &VAL = 3000 

STYPE X'SVAL STYPE BB8 

STYPE XM3107299 STYPE 2000 

In the last statement above, the characters 99 are truncated before 
substitution occurs, since EXEC tokens can be a maximum of 8 
characters. 

To suppress hexadecimal conversion during an EXEC procedure after 
having used it, you can use the EXEC control statement 

SHEX OFF 

so you can use tokens containing the characters X 1 without the EXEC 
processor converting them to hexadecimal. 



Arguments 

An argument in an EXEC procedure is one of the special variable symbols 
SI through &30 that are assigned values when the EXEC is invoked. For 
example, if the EXEC named LINKS is invoked with the line 

links viola ariel oberon 

the tokens VIOLA, ARIEL, and OBERON are arguments, and are assigned to 
the variable symbols &1, 62, and S3, respectively. 
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You can pass as many as 30 arguments to an EXEC procedure; thus the 
variable symbols you can set range from & 1 to &30. These variables are 
collectively referred to as the special variable Sn. Once these symbols 
are defined, they can be used and manipulated in the same manner as any 
other variable in an EXEC. They can be tested, displayed, changed, and, 
if they contain numeric quantities, used arithmetically. 

&IF 82 EQ PRINT &G0T0 -PR 
&TYPE 81 IS AH INVALID ARGUMENT 
81 = 2 
8CT = 81 + 100 

The above examples illustrate some explicit methods of manipulating the 
Sn variables. They can also be implicitly defined or redefined by two 
EXEC control statements: &ARGS and &READ ARGS. 

An &ARGS control statement redefines all of the special 8n 
variables. The statement 

8ARGS ABC 

assigns the value of A, B, and C to the variables 81, 82, and 83 and 
sets the remaining variables, 84 through 830, to blanks. 

You can also redefine arguments interactively by using the &READ ARGS 
control statement. When EXEC processes this statement, a read request is 
presented to your terminal, and the tokens you enter are assigned to the 
8n variables. For example, the lines 

&TYPE ENTER FILE NAME AND TYPE: 
&READ ARGS 
STATE 81 82 * 

request you to enter two tokens, and then treat these tokens as the 
arguments 81 and 82. The remaining variables 83 through 830 are set to 
blanks. 

If you want to redefine specific &n variables, and leave the values 
of others intact, you can either redefine the individual variables in 
separate assignment statements, cr use the variable symbol in the &ARGS 
or &READ ARGS statement. For example, the statement 

&ARGS CONT 82 83 RETURN 85 86 87 88 89 810 

assigns new values to the variables 81 and 84 , but does not change the 
existing values for the remaining symbols through 8 10. 

If you need to set an argument or 8n special variable to blanks, 

either on an EXEC command line or in an &ARGS or BREAD ARGS control 

statement, you can use a percent sign (%) in its place. For example, the 
lines: 

6ARGS SET QUERY % TYPE 
8TYPE 81 82 83 84 

result in the display 

SET QUERY TYPE 

The symbol 83 has a value of blanks, and as a null token, is discarded 
from the line. 
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USING THE SINDEX SPECIAL VARIABLE 

The EXEC special variable, SINDEX, initially contains a numeric value 
corresponding to the number of arguments defined when the EXEC was 
invoked. The value of SINDEX is reset whenever an SABGS or &READ ARGS 
control statement is executed. 

&INDEX can be useful in many circumstances. If you create an EXEC 
that may expect any number of arguments, and you are going to perform 
the same operation for each, you might set a counter and use the value 
of SINDEX to test it. For example, an EXEC named PRINTX accepts 
arguments that are the filenames of ASSEMBLE files: 

SCT = 1 

SLOOP 2 SCT > SINDEX 
PRINT 88CT ASSEMBLE 
SCT = SCT + 1 

In the preceding example, the token SCT is substituted with &1, S2, and 
so on until all of the arguments entered on the PRINTX line are used. 

You can also use SINDEX to test the number of arguments entered. If 
you design an EXEC to expect at least two arguments, the procedure might 
contain the statements: 

&IF SINDEX LT 2 SGOTO -ERR1 



-ERR1 &TYPE INVALID COMMAND LINE 
SEXIT 1 

In this example, if the EXEC is invoked with one or no arguments, an 
error message is displayed and the EXEC terminates processing with a 
return code of 1. 

As another example, suppose you wanted to supply an EXEC with default 
arguments, which might or might not be overridden. If the EXEC is 
invoked with no arguments, the default values are in effect; if it is 
invoked with arguments, the arguments replace the default values: 

SDISP = PRINT 

SCOUNT = 2 

SIF SINDEX GT 2 SEXIT 1 

&IF SINDEX EQ SGOTO -GO 

SCOUNT = S1 

SIF SINDEX = 2 SDISP = S2 

-GO 

Default values are supplied for the variables SDISP and SCOUNT. Then, 
SINDEX is tested, and the variables are reset if any arguments were 
entered. 



CHECKING ARGUMENTS 

There are a number of tests that you can perform on arguments passed to 
an EXEC. In some cases, you may want to test for the length of a 
specific argument or to test whether an argument is character data or 
numeric data. To perform these tests, you can use the EXEC built-in 
functions &LENGTH and SDATATYPE. 
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To use either SLENGTH or SDATATYPE, you must first assign a variable 

to receive the result of the function, and then test the variable. For 

example, to test whether an entered argument is 5 characters long, you 
could use the statements: 

SLIMIT = SLENGTH 81 

SIF 8LIMIT GT 5 &EXIT SLIMIT 

When these statements are executed, if the first argument (&1) is 
greater than 5 characters, the exit is taken, and the return code 
indicates the length of 61. 

If you wish to check whether a number was entered for an argument, 
use the &DATATYPE function: 

&STRING = SDATATYPE S2 

&IF &STRING -»= NUM SGOTO -BRR4 

In this example, the second argument expected by the EXEC must be a 
numeric guantity. If it is not, a branch is taken to an error exit 
routine. 

Often, you may create an EXEC that tests for specific arguments and 
then takes various paths, depending on the argument. For example: 

SIF &2 = PRINT SGOTO -PR 
SIF 82 = TYPE SGOTO -TY 
SIF 82 = ERASE SGOTO -ER 
SEXIT 

In this EXEC, if the value of 82 is not PRINT, TYPE, or ERASE, or was 
not entered, the EXEC terminates processing. 



S* and 



There are two special EXEC keywords that you may use to test arguments 
passed in an EXEC. They are 8* and 8$, which can be used only in an SIF 
or an 8L00P control statement. They test the entire range of numeric 
variables 81 through 830, as follows: 

8$: The special token 8$ is interpreted as "any of the variables 81, 82, 
..., 830." That is, if the value of any one of the numeric variables 
satisfies the established condition, then the 8IF statement is 
considered to be true. The statement is false only when none of the 
variables fulfills the specified requirements. 

As an example, suppose you want to make sure that some particular 
value is passed to the EXEC. You can check to see if any of the 
arguments satisfy this condition, as follows: 

8IF 8$ EQ PRINT &SKIP 2 

&TYPE PARM LIST MUST INCLUDE PRINT 

&EXIT 

In this example, the path to the &TYPE statement is taken only when none 
of the arguments passed to the EXEC procedure egual the character string 
PRINT. 
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8#: The special token &* is interpreted as "all of the variables £1, 82, 
. ., . , 630." That is, if the value of each of the numeric variables 
satisfies the established condition, then the &IF statement is 
considered to be true. The statement is false when at least one of the 
variables fails to meet the specified requirements. 

Use 8* to test for the absence of an argument as follows: 

GIF 8* NE ASSEMBLE &EXIT 3 

In this example, if an EXEC is invoked, and none of the arguments equals 
ASSEMBLE, the EXEC terminates with a return code of 3. 

The tokens 8* and 8$ are set by arguments entered when an EXEC is 
invoked and reset when you issue an 8ARGS or 8BEAD ARGS control 
statement. If either 8* or 8$ is null because no arguments are entered, 
the 8IF statement is considered a null statement, and no error occurs. 



Execution Paths in an EXEC 



You have already seen examples of the &IF, &G0T0, SSKIP, and 8L00P 
control statements. A more detailed discussion on each of these 
statements and additional techniques for controlling execution paths in 
an EXEC procedure follow. 



LABELS IN AM EXEC PROCEDURE 



In many instances, an execution control statement in an EXEC procedure 
causes a branch to a particular statement that is identified by a label. 
The rules and conventions for creating syntactically correct EXEC labels 
are: 



A label must begin with a hyphen (dash) , and must 
additional character following the hyphen. 



have at least one 



Up to seven additional alphameric characters may follow 
(with no intervening blanks) . However, the sequence, 

8G0T0 -PROBABLY 



the hyphen 



-PROBABLY 

executes successfully, because when each statement is scanned, the 

token -PROBABLY is truncated to the same 8 -character token, 
-PROBABL. 



A label name may 
statement. 



be the object of an 8G0T0 or 8L00P control 



A label that is branched to must be the first token on a line. It 
may stand by itself* with no other tokens on the line, or it may 
precede an executable CMS command or EXEC control statement. 
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The following are examples of the correct use of labels: 

8G0T0 -LAB1 

-LAB1 

-LAB2 SCCNTINUE 

-CHECK 6IF SINDEX EC SGOTO -EXIT 

SIF SINDEX LT 5 &SKIP 

-EXIT 6EXIT 4 

STYPE SLITERAL SINDEX VALUE IS SINDEX 



CONDITIONAL EXECUTION WITH THE &IF STATEMENT 

The main tool available to you for controlling conditional execution in 
an EXEC procedure is the SIF control statement. The &IF control 
statement provides the decision-making ability that you need to set up 
conditional branches in your EXEC procedure. 

One approach to decision-making with the SIF control statement is to 
compare two tokens, and perform some action based on the result of the 
comparison. When the comparison specified is egual (or true) , the 
executable statement is executed. When the comparison is unequal (or 
false) , control passes to the next sequential statement in the EXEC 
procedure. An example of a simple &IF statement is: 

SIF &1 EQ &2 &TYPE MATCH FOUND 

If the comparand values are not equal, the statement &TYPE MATCH 
FOUND is not executed, and control passes to the next statement in the 
EXEC procedure. If the comparand values are equal, the statement STYPE 
MATCH FOUND is executed before control passes to the next statement. 
SIF statements can also be used to establish a ccmparison between a 
variable and a constant. For example, if a terminal user could properly 
enter a YES or NO response to a prompting message, you could set up SIF 
statements to check the response as follows: 

SREAD ARGS 

SIF &1 EQ YES &GOTO -YESANS 

SIF S1 EQ NO SGOTO -NOANS 

STYPE S1 IS NOT A VALID RESPONSE (MUST BE YES OB NO) 

8EXIT 

-YESANS 



-NOANS 



In this example, the branch to -YESANS is taken if the entered 
argument is YES; otherwise, control passes to the next SIF statement. 
The branch to -NOANS is taken if the argument is NO; otherwise, control 
passes to the STYPE statement, which displays the entered argument in an 
error message and exits. 

The test performed in an SIF statement need not be a simple test of 
equality between two tokens; other types of comparisons can be tested, 
and more than two variables can be involved. The tests that can be 
performed and the symbols you can use to represent them are: 
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Sljnbol Mnemonic Meaning 

= EQ A equals B 

-«= NE A does not equal B 

< LT A is less than B 

<= LE A is less than or equal to B (not qreater than) 

> GT A is greater than B 

>= GE A is greater than or equal to B (not less than) 



Compound SIF Statements 

You can place multiple SIF control statements on one line, to test a 
variable for more than one condition. For example, the statement 

SIF SNUM GT 5 &IF &NUM LT 10 &TYPE O.K. 

checks the variable symbol SNUM for a value greater than 5 and less than 
10. If both of these conditions are satisfied, the &IF statement is 
true, and the &TYPE statement is executed. If either condition is false, 
then the STYPE statement is not executed. 

The number of &IF statements that may be nested is limited only by 
restrictions placed on the record length of the EXEC file. 



BRANCHING WITH THE &GOTO STATEMENT 

The 8G0T0 control statement allows you to transfer control within your 
EXEC procedure 

• To a specified EXEC label somewhere in the EXEC file: 

&GOTO -TEST 
where -TEST is the label to which control is passed. 

• To a particular line within the EXEC file. For example, 

SGOTO 15 
results in control being passed to statement 15 in the EXEC file. 

• Directly to the top of the EXEC file. For example, 

&GOTO TOP 

passes control to the beginning of the EXEC procedure. 

The &GOTO control statement can be coded wherever an executable 
statement is permitted in an EXEC procedure. One of its common uses is 
in conjunction with the SIF control statement. For example, in the 
statement: 

SIF &INDEX EQ SGOTO -ERROR 

the branch to the statement labeled -ERROR is taken when the value of 
the &INDEX special variable is zero. Otherwise, control passes to the 
next sequential statement in the EXEC procedure. 
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An 8G0T0 statement can also stand alone as an EXEC control statement. 
When coded as such, it forces an unconditional branch to the specified 
location. For example, you might create an EXEC that has several 
execution paths, each of which terminates with an &GOTO statement 
leading to a common exit routine: 

-PATH1 6C0NTINUE 



SGOTO -EXIT 
-PATH2 SCONTINUE 



SGOTO -EXIT 
&PATH3 &CONTIN0E 



-EXIT SCONTINUE 

Xou can use the 6G0TC control statement to establish a loop. For 
example: 

6GL0BAL1 = SGL0BAL1 + 1 

6TYPE ENTER NUMBER: 

BREAD VARS SNEXT 

&IF .SNEXT = . SGOTO -FINIS 

SIF SGL0EAL1 = 2 STOTAL = 

STOTAL = STOTAL + SNEXT 

SGOTO TOP 

-FINIS 

STYPE TOTAL IS STOTAL 

In this EXEC example, all of the statements, through the SGOTO TOP 

statement, are executed repeatedly until a null line is entered in 

response to the prompting message. Then, the branch is taken to the 
label -FINIS and the total is typed. 

Note the use of the special variable SGL0BAL1 in the preceding 
example. The SGLOBALn special variables are self-initializing, and have 
an initial value of 1. 



Using the &.GOTO Control Statement 

When an EXEC procedure processes an SGOTO statement, and searches for a 
given label or line number, the scan begins on the line following the 
SGOTO statement, proceeds to the bottom of the file, then wraps around 
to the top of the file and continues to the line immediately preceding 
the SGOTO statement. If there are duplicate labels in an EXEC file, the 
first label encountered during the search is the one that is branched 
to. 

If the label or line number is not found during the scan, EXEC 
terminates processing and displays the message: 

ERROR IN EXEC FILE filename, LINE n - &SKIP or SGOTO ERROR 

If the label or line number is found, control is passed to that location 
and execution continues. 
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BRANCHING WITH THE &SKIP STATEMENT 

The &SKIP control statement provides you with a second method of passing 
control to various points in an EXEC procedure. Instead of branching to 
a named or numbered location in an EXEC procedure, 8SKIP passes control 
a specified number of lines forward or backward in the file. 

You pass control forward in an EXEC by specifying how many lines to 
skip. For example, to handle a conditional exit from an EXEC procedure, 
you could code the following: 

SIF 8RETC0DE EQ &SKIP 
&EXIT &RETCODE 

where the SEXIT statement is skipped whenever the value of SRETCODE 
equals zero. If the value of &RETCODE does not equal zero, control 
passes out of the current EXEC procedure with a return code that is the 
nonzero value in SRETCODE. Note that when no SSKIP operand is 
specified, a value of 1 is assumed. 

A succession of SSKIP statements can be used to perform multiple 
tests on a variable. For example, suppose an argument should contain a 
value from 5 to 10 inclusive: 

SIF 81 LT 5 SSKIP 

SIF &1 LE 10 SSKIP 

STYPE 81 IS NOT WITHIN RANGE 5-10 

If the value of 81 is less tha*n 5, control passes to the STYPE control 
statement, which displays the erroneous value and an explanatory 
message. If the value of 61 is greater than or equal to 5, the next 
statement checks to see if it is less than or equal to 10. If this is 
true, then the value is between 5 and 10 inclusive, and execution 
continues following the 8TYPE statement. 

When you want to pass control to a statement that precedes the 
current line, determine how many lines backward you want to go, and code 
SSKIP with the desired negative value: 

&VAL = 1 

STYPE SVAL 

8VAL = SVAL + 1 

SIF SVAL NE 10 SSKIP -2 

In this EXEC, the STYPE statement is executed repeatedly until the value 
of SVAL is 10, and then execution continues with the statement following 
the SIF statement. 

USING COUNTERS FOR LOOP CONTROL 

A primary consideration in designing a portion of an EXEC procedure that 
is to be executed many times is how to control the number of 
executions. One way to control the execution of a sequence of 
instructions is to create a loop that tests and changes the value of a 
counter. 

Before entering the loop, the counter is initialized to a value. 
Each time through the loop, the counter is adjusted (increased or 
decreased) toward a limit value. When the limit value is reached (the 
counter value is the same as the limit value), control passes out of the 
loop and it is not executed again. For example, the following EXEC 
initializes a counter based on the argument &1: 
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SIF &INDEX EQ &EXIT 12 

STYPE COUNT IS &1 

&1 = &1 - 1 

SIF 81 GT &SKIP -2 

When this EXEC procedure is invoked, it checks that at least one 
argument was passed to it. If an argument is passed, it is assumed to 
be a number that indicates how many times the loop is to execute. Each 
time it passes through the loop, the value of &1 is decremented by 1. 
When the value of &1 reaches zero, control passes from the loop to the 
next seguential statement. 

There are several ways of setting, adjusting, and testing counters. 
Some ways to set counters are by: 

• Reading arguments from a terminal, such as: 

SREAD VABS &C0UNT1 &C0UNT2 

• Assigning an arbitrary value, such as: 

&COUNTER = 43 

• Assigning a variable value or expression, such as: 

&COUNTS = &INDEX - 1 

Counter values can be increased or decreased by any increment or 
decrement that meets your purposes. For example: 

&COUNTEM = &COUNTEM - &RETCODE 
SC0UNT1 = &COUNT + 100 



LOOP CONTROL WITH THE &LOOP STATEMENT 

A convenient way to control execution of a seguence of EXEC statements 
is with the SLOOP control statement. An SLOOP statement can be set up 
in four ways: 

• To execute a particular number of statements a specified number of 
times. For example, the statement 

&LOOP 3 2 

indicates that the three statements following the SLOOP, statement are 
to be executed twice. 

• To execute a particular number of statements until a specified 
condition is satisfied. For example: 

SLOOP 4 &X = 

The four statements following this statement are executed until the 
value of SX is 0. 

• To execute the statements down to (and including) the statement 
identified by a label for a specified number of times. For example: 

SLOOP -ENDLOOP 6 

The statements between this SLOOP statement and the label -ENDLOOP 
are executed six times. 
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• To execute the statements down to (and including) the statement 
identified by a label until a specified condition is satisfied. In 
the following example 

SLOOP -ENDLOOP SX = 

the statements are executed repeatedly until the value of &X is 0. 

The numbers specified for the number of lines to execute and the 
number of times through the loop must be positive integers. You can use 
a variable symbol to represent the integer. If a label is used to 
define the limit of the loop, it must follow the SLOOP statement (it 
cannot precede the &LOOP statement) . 

In a conditional SLOOP statement, any variable symbols in the 
conditional phrase are substituted each time the loop is executed. For 
example, the statements: 

SX = 

SLOOP -EBD SX EC 2 

SX = SX + 1 

-END STYPE SX 

are interpreted and executed as follows: 

1. The variable SX is assigned a value of 0. 

2. The SLOOP statement is interpreted as a conditional form; that is, 
to loop to -END until the value of SX eguals 2. Since the value of 
SX is not 2, the loop is entered. 

3. The variable SX is incremented by 1 and is then displayed. 

4. Control returns to the beginning of the loop, where SX is tested to 
see if it eguals 2. Since it does not, the loop is executed again 
and 2 is displayed. The next time through the loop, when SX eguals 
2, control is passed to the EXEC statement immediately following 
the label -END. 

When this EXEC procedure is executed, the following lines are 
displayed: 

1 

2 

at which time the value of SX eguals 2; the loop is not executed again. 

Another example of a conditional loop is: 

SY = SLITEEAL ASB 
SLOOP 2 .SX EQ &LITERAL .6 
SX = SSUBSTR SY 2 1 
STYPE SX 

These statements are interpreted and executed as follows: 

1. The variable SY is set to the literal value ASB. 

2. The two statements following the SLOOP statement are to be executed 
until the value of SX is S. 

3. The SSUBSTR built-in function is used to set the variable SX to the 
value of the second character in the variable SY, which is a 
literal ampersand (S) . 
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4. The ampersand is typed once, and the loop does not execute again 
because the condition that the value of SX be a literal ampersand 
is met. 



NESTING EXEC PROCEDURES 

If you want to use an EXEC procedure within another EXEC, you must use 
the EXEC command to execute it. For example, if you have the statement 

EXEC TEST 

in an EXEC procedure, it invokes the EXEC procedure TEST. 

The EXEC interpreter can handle up to 19 levels of recursion at one 
time, that is, up to 19 EXECs may be active, one nested within another. 
An EXEC may also call itself. 

You can test the SGLOBAL special variable to see if an EXEC is 
executing within another procedure or not. For example, if the file 
GLOBAL EXEC contained the lines: 

SIF SGLOBAL EQ 2 SGOTO -2NDPASS 



EXEC GLOBAL 



-2NDPASS &TYPE SECOND PASS BEGINS 

then when the line "EXEC GLOBAL" is executed, control passes to the 
beginning of the EXEC; the value of SGLOBAL changes from 1 to 2; and 
control is passed to the &TYPE statement at the label 2NDPASS. 



Passing Arguments to Nested Procedures 

Variables in an EXEC file have meaning only within the particular 
procedure in which they are defined. You cannot set up a variable in one 
EXEC, and test that variable in a nested procedure. The exceptions to 
this are the ten special variables &GLOBAL0 through &GL0BAL9. These 
variables can only contain integral numeric values; you cannot assign 
them character-string values. These variables can be used to set up 
arguments to pass to nested procedures, or to communicate between EXEC 
files at different recursion levels. 



EXITING FROM EXEC PROCEDURES 

Execution in an EXEC procedure proceeds seguentially through a file, 
line by line. When a statement causes control to be passed to another 
statement, execution continues at the second statement, and again 
proceeds seguentially through the file. When the end of the file is 
reached, the EXEC terminates processing. Freguently, however, you may 
not want processing to continue to the end of the file. You can use the 
SEXIT statement to cause an immediate exit from EXEC processing and a 
return to the CMS environment. If the EXEC has been invoked from 
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another EXEC, control is returned to the calling EXEC file. For 
example, the statement 

GIF SRETCODE -»= SEXIT 

would cause an immediate exit from the EXEC if the return code from the 
last issued CMS command was not zero. 

You can use the SEXIT statement to terminate each of a series of 
execution paths in an EXEC. For example, using the following 
statements, 

6IF &1 EQ PRINT SGOTO -PRINT 
6IF 81 EQ TYPE SGOTO -TYPE 



-PRINT 



SEXIT 
-TYPE 



SEXIT 

you ensure that once the path through the -PRINT routine has been taken, 
the EXEC does not continue processing with the -TYPE routine. 



i!i|ssinc[ Return Codes From EXECs 

The SEXIT control statement also provides a special function, which 
cillows you to pass a return code to CMS, or to the program or EXEC which 
called this EXEC. You specify the return code value on the SEXIT 
control statement as follows: 

SEXIT 4 

Execution of this line results in a return to CMS with a Ready message: 

R(00004) ; 

If you have a variety of exits in an EXEC, you can use a different value 
following each SEXIT statement, to indicate which path had been taken in 
the EXEC. 

You can also use a variable symbol as the value to be passed as the 
return code: 

SEXIT &VAL 

Another common use of the SEXIT statement is to cause an exit to be 
taken following an error in a CMS command, and using the return code 
from the CMS command in the SEXIT statement: 

&IF SRETCODE NE SEXIT SRETCODE 
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Terminal Communications 

You can design EXECs to be used interactively, so that their execution 
depends on information entered directly from the terminal during the 
execution. With the &TYPE statement, you can display a line at the 
terminal, and with the SREAD statement, you can read one or more lines 
from the terminal or console stack. Used together, these statements can 
provide a prompting function in an EXEC: 

STYPE WHAT DO YOU WANT TO DO NOW? 

&TYPE ENTER (STOP CONTINUE REPEAT) : 

SREAD VARS SLABEL 

&GOTO -&LABEL 
-STOP 



-CONTINUE 



-REPEAT 



In this example, the SREAD control statement is used with the VARS 
operand, which accepts the words entered at the terminal as values to be 
assigned to variable symbols. If the word STOP is entered in response to 
the &READ VARS statement in this example, the variable symbol &LABEL is 
assigned the value STOP. Then, in the &GOTO statement, the symbol is 
substituted with the value STOP, so the branch is taken to the label 
-STOP. 

You can specify up to 17 variable names on an SREAD VARS control 
statement. If you enter fewer words than are expected, the remaining 
variables are set to blanks. If you enter a null line, any variable 
symbols on the SREAD line are set to blanks. If the execution of your 
EXEC depends on a value entered as a result of an SREAD VARS, you might 
want to include a test for a null line immediately following the 
statement, for example: 

SREAD VARS STITLE &SUBJ 
&IF .STITLE = . &EXIT 100 

If no tokens are entered in response to the terminal read reguest, the 
variable STITLE is null, and the EXEC terminates with a return code of 
100. 

If you are writing an EXEC that may receive a number of tokens from 
the terminal, you may find it more convenient to use the SREAD ARGS form 
of the SREAD control statement. When the SREAD ARGS statement reads a 
line from the terminal, the tokens entered are assigned to the 8n 
special variables (81, &2, and so on). 

READING CMS COMMANDS AND EXEC CONTROL STATEMENTS FROM THE TERMINAL 

When you use the SREAD control statement with no operands, or with a 
numeric value, EXEC reads one line or the specified number of lines from 
the terminal. These lines are treated, by EXEC, as if they were in the 
EXEC file all along. For example, if you have an EXEC named COMMAND that 
looks like the following: 
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&TYPE ENTER NEXT COMMAND: 
8READ 1 
&SKIP -2 

all the commands you enter during the terminal session are processed by 
the EXEC. Each time the &READ statement is executed, you enter a CMS 
command. When the command finishes, control returns to EXEC, which 
prompts you to enter the next command. since the CMS commands are all 
being executed from within the EXEC, you do net receive the CMS Ready 
message at the completion of each command. 

You could also enter EXEC control statements or assignment 
statements. To terminate the EXEC and return to the CMS environment, 
you must enter the EXEC control statement &EXIT from the terminal: 

Sex it 



DISPLAYING DATA AT A TERMINAL 

You can use the &TYPE and &BEGTYPE control statements to display lines 
from your EXEC at the terminal. In addition, you can use the CMS TYPE 
command to display the contents of CMS files. 

When you use the &TYEE control statement, you can display variable 
symbols as well as data. Variable symbols on an 6TYPE control statement 
are substituted before they are displayed. For example, the lines: 

&NAME = ARCHER 
&TYPE SNAME 

result in the display: 

ARCHER 

You can use the 8TYPE statement to display prompting messages, error 
or information messages, or lines of data. 

In an EXEC file with fixed-length records, only the first 72 
characters of each line are processed by the EXEC interpreter. 
Therefore, if you want to use the &TYPE control statement to display a 
line longer than 72 characters, you must convert the file into 
variable-length records. 



!>BEGTYPE and SBEGTYPE ALL 

All of the words in an &TYPE control statement are scanned into 
8-character tokens. If you need to display a word that has more than 8 
characters, you must use the &EEGTYPE control statement. The SBEGTYPE 
control statement precedes one or more data lines that you want to 
display, for example: 

SBEGTYPE 

THIS EXEC PERFOBMS THE FOLLOWING FUNCTIONS: 

1. IT ACCESSES DISKS 193, 194, and 195 AS 
B, C, AND D EXTENSIONS OF THE A-DISK. 

2. IT DEFINES, FORMATS, AND ACCESSES A 
TEMPORARY 195 DISK (E) . 

SEND 
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The SEND statement must be used to terminate a series of lines 
introduced with the SBEGTYPE statement. "SEND" must begin in column 1 of 
the EXEC file. 

The lines following an SBEGTYPE statement, up to the SEHD statement, 
are not scanned by the EXEC interpreter. Therefore, no substitution is 
performed on the variable symbols on these data lines. If you need to 
display a symbol, you must use the &TYPE control statement. To display a 
combination of scanned and unscanned lines, you might need to use both 
the &TYPE and SBEGTYPE control statements: 

SBEGTYPE 

EVALUATION BEGINS... 

SEND 

&TYPE &VAL1 IS &NUM1. 

STYPE SVAL2 IS &NUH2. 

SBEGTYPE 

EVALUATION COMPLETE. 

SEND 

If you use the SBEGTYPE control statement in an EXEC file with 
fixed-length records, and you want to display lines longer than 72 
characters, you must use the ALL operand. For example, 

SBEGTYPE ALL 

...data line of 103 characters 

...data line of 98 characters 

...data line of 50 characters 

SEND 

You can display lines of up to 130 characters in this way. When you 
enter lines that are longer than the record length in an EXEC file, the 
records are truncated by the editor. You must increase the record length 
of the file by using the LRECL option of the EDIT command, for example: 

edit old exec a (lrecl 130 

In a variable- length EXEC file, you do not need to specify ALL to 
display long lines. If you originally created the file with a record 
length of 130 characters, you do not need to increase the size later to 
accomodate longer records. 



Usina the CHS TYPE Command 

You can use the TYPE command in an EXEC file to display data files, or 
portions of data files. For example, you might have a number of files 
with the same filetype; the files contain various kinds of data. You 
could create an EXEC that invoices the TYPE command to display a 
particular file as follows: 

SIF SINDEX EQ 2 &IF 62 EQ ? SGOTO -TYPE 



-TYPE 

ACCESS 198 B 
TYPE &1 MEMO B 

The filetype MEMO is a reserved filetype, which accepts data in 
uppercase and lowercase; you can use it for documentation files or 
programming notes. 
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Controlling Terminal Displays 

The two CMS Immediate commands that control terminal display are HT 
(halt typing) and RT (resume typing) . When data is being displayed at 
your terminal, you can suppress the display by signaling an attention 
interrupt and entering: 

ht 

This command affects output that is being displayed: 

» As a response to a CMS command, including prompting messages, error 
messages, or normal display responses (as from the TYPE command) 

• From a program 

• In response to an STYPE or SBEGTYPE request in an EXEC 

Once display has been suppressed, and before the command, program, or 
EXEC completes execution, you can request that display be resumed by 
signaling another interrupt and entering: 

rt 

In an EXEC file, if you want to halt or resume display, you must use 
the &STACK control statement to enter the RT or HT commands. For 
example, the ACCESS command issues a message when a disk is accessed: 

D(198) R/0 

If you are going to issue the ACCESS command within an EXEC and you do 
not wish this message displayed, you could enter the lines: 

&STACK HT 
ACCESS 198 D 

Once you have stacked an HT command, all displaying is suppressed for 
the remainder of the EXEC file's execution, unless the RT Immediate 
command is processed, either following an attention interrupt (as 
described above) or within the EXEC. To execute the RT Immediate 
command in an EXEC, use the statement: 

&STACK RT 

A physical read to the terminal, for example, the result of an &READ 
control statement, also resets the display setting to RT. 

The STYPEFLAG Sp_ecial Variable: You can test the current value of the 
display controlling an~EXEC with the STYPEFLAG special variable. The 
value of STYPEFLAG can only be one of the literal values HT or RT. For 
example: 

SIF &$ EQ NOTYPE &STACK HT 



8IF STYPEFLAG EC HT &SKIP 3 

STYPE LINE1 

STYPE LIUE2 

STYPE LIHE3 

SCOHTINUE 

In this example, if NOTYPE is entered as an argument when the EXEC is 
invoked, an HT command is stacked, so that no displaying is done at the 
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terminal. Within the EXEC, the variable STYPEFLAG is tested, and, if it 
is HT, then a series of &TYPE statements is skipped. Since EXEC does 
not have to process these lines, you can save time and system resources 
by not processing them. 



Reading from the Console Stack 

When you are in the CMS environment executing programs or CMS commands, 
you can stack commands, either by entering multiple command lines 
separated by the logical line end symbol, as follows: 

print myfile listing#cp guery printer 

or by signaling an attention interrupt and entering a command line, as 
follows: 

print myfile listing 

! 

cp guery printer 

In both of the preceding examples, the second command line is saved 
in a terminal input buffer, called the console stack. Whenever a read 
occurs in your virtual machine, CMS reads lines from the console stack, 
if there are any lines in it. If there are no lines in the stack, the 
read results in a physical read to your terminal (on a typewriter 
terminal, the keyboard unlocks). 

A virtual machine read occurs whenever a command or subcommand 
finishes execution, or when an EXEC or a program issues a read reguest. 
Many CMS commands also issue read reguests, for example, SORT and 
COPYFILE. If you want to execute one of these commands in an EXEC, you 
■ay want to stack, in the console stack, the response to the read 
reguest so that when it is issued it is immediately satisfied. For 
example: 

SSTACK 42-121 1 

COPYFILE &NAME LISTING A = ASSEMBLE = (SPECS 

When the COPYFILE command is issued with the SPECS option, a prompting 
message for a specification list is issued, followed by a read reguest. 
In this EXEC, the reguest is satisfied with the line stacked with the 
SSTACK control statement. If the response was not stacked, you would 
have to enter the appropriate information from the terminal during the 
execution of the EXEC that contained this COPYFILE command line. 

In addition to stacking predefined responses to commands and 
programs, you can use the console stack to stack CMS commands and EDIT 
subcommands, as well as data lines to be read within the EXEC. 

The number of lines that you can place in the console stack at any 
one time varies according to the amount of storage available in your 
virtual machine for stacking. You may want to stack one or two lines at 
a time, or you may wish to stack many lines. There are several features 
available in EXEC that can help you manipulate the stack. 



&BEGSTACK and SBEGST ACK ALL 

Just as the STYPE control statement has an SBEGTYPE counterpart, the 
SSTACK control statement has an SBEGST ACK counterpart. You can stack 
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multiple data lines following an SBEGSTACK statement. Lines stacked in 
this way are not scanned by the EXEC processor, and no substitution is 
performed on variable symbols. For example, the lines 

SBEGSTACK 

. . . line of data 

. . .line of data 

...line of data 

SEND 

stack three data lines in the stack. The stacked lines must be followed 
by an SEND control statement, which must be entered in the EXEC file 
beginning in column 1. 

If you have an EXEC with fixed- length records, and you want to stack 
data lines longer than 72 characters, you must use the ALL operand of 
the &BEGSTACK control statement: 

SBEGSTACK ALL 

...line of 103 characters 

...line of 98 characters 

...line of 60 characters 

SEND 

The ALL operand is not necessary for variable-length EXEC files. 



Stacking FIFO and LIFO 

When you are stacking multiple lines in an EXEC, you may choose to 
reverse the sequence in which lines are read in from the stack. The 
default sequence is FIFO (first-in, first-out) , but you may specify LIFO 
(last-in, first-out) when you enter the SSTACK or SBEGSTACK control 
statement. For example, execution of the lines 

SSTACK &TYPE A 
SSTACK STYPE B 
SSTACK LIFO STYPE C 
SSTACK LIFO STYPE D 
SSTACK STYPE E 

results in the display: 

D 
C 
A 
B 
E 



lk§ SREADFLAG Special Variable 

The EXEC special variable &READFLAG always contains one of two values, 
STACK or CONSOLE. When it contains the value STACK, it indicates that 
there are lines in the stack. When it contains the value CONSOLE, it 
indicates that the stack is empty and that the next read request results 
in a physical read to the terminal (console) . 

You can test this value in an EXEC, for example: 
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8IF 8EEADFLAG EQ STACK 8SKIP 2 

8TYPE STACK EMPTY 

&EXIT 

&CONTINUE 

You might use a similar test in an EXEC that processes a number of lines 
from the stack, and loops through a series of steps until the stack is 
empty. 

STACKING CMS COMMANDS 

Whenever you place a command in the console stack, it remains there 
until a read request is presented to the terminal. If the request is the 
result of an &READ control statement, then the line is read from the 
stack. For example, the lines 

8STACK CP QUERY TIME 
SREAD 

result in the command line being stacked, read in, and then executed. 

If there are no read requests in an EXEC file, then any commands that 
are stacked are executed after the EXEC has finished and has returned 
control to the CMS environment. For example, consider the lines: 

TYPE 81 LISTING A 
ACCESS 198 A 
TYPE 81 LISTING A 

If this EXEC is located on your 191 A-disk, then when the ACCESS command 
accesses a new A-disk, CMS can not continue reading the EXEC file, and 
issues an error message. However, if the EXEC was written as follows: 

TYPE 81 LISTING A 
8STACK ACCESS 198 A 
&STACK TYPE 81 LISTING A 

then, after the TYPE command, the next command lines are stacked, the 
EXEC finishes executing and returns control to CMS, which reads the next 
command lines from the console stack. 

When you stack CMS commands in an EXEC procedure, you cannot place 
multiple command lines in one statement (for example, print abc 
listing#print xyz listing) , because CMS does not recognize the logical 
line end (X»15») . 

Stacking EDIT Subcommands 

If you want to issue the EDIT command from within an EXEC, you might 
want to stack EDIT subcommands to be read by the CMS Editor. You should 
stack these subcommands, either with &STACK statements, or with the 
&BEGSTACK statement, just before issuing the EDIT command. For example: 

&BEGSTACK 

CASE M 

GET SETUP FILE A 1 20 

TOP 

LOCATE /XX/ 

&END 

&STACK REPLACE 

EDIT 81 DATA (LRECL 120 
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If this EXEC is named EDEX, and you invoke it with 

edex fr01 

the EDIT subcommands are stacked in the order they appear in the EXEC. 
The EDIT command is invoked to edit the file FR01 DATA, and the EDIT 
subcommands are read from the stack and executed. When the stack is 
empty, your virtual machine is in the edit environment in input mode, 
and the first line you enter replaces the existing line that contains 
the character string XX. 

Note that all of the EDIT subcommands in the example, except for the 
REPLACE subcommand, are stacked within an SBEGSTACK stack, and that the 
REPLACE subcommand is stacked with SSTACK. If you are creating EXEC 
files with fixed-length records, you must use SSTACK to stack the INPUT 
and REPLACE subcommands. If you use &BEGSTACK, then the INPUT and 
REPLACE subcommands are treated as if they contain text data, and so 
insert or replace one line in the file (a line of blanks) . This is not 
true, however, for variable-length EXEC files. 

Similarly, if you want to stack a null line, to change from input 
mode to edit mode in an EXEC, you must use the SSTACK statement with no 
other data on the line (in both fixed- and variable-length EXEC files) , 
for example: 

SSTACK INPUT 
SBEGSTACK 
...data line 
...data line 
...data line 
SEND 
SSTACK 
SSTACK FILE 
EDIT 61 S2 
SEX IT 

When this EXEC is invoked with a filename and filetype as arguments, the 
INPUT subcommand, data lines, null line, and FILE subcommand are placed 
in the stack before the EDIT command is issued. The data lines are 
placed in the specified file and the file is written onto disk before 
the EXEC returns control to CMS. 



STACKING LINES FOR EXEC TO READ 

Lines in the console stack can be read by the EXEC interpreter with an 
&REAE control statement, for example, 

-SETUP 

SLOOP 3 SNUM = 50 

SSTACK &NUH &CHAR 

SNUM = SNUM + 1 

SCHAR = &C0NCAT SSTRNG SNUM 



-READ 

SLOOP -FINIS &READFLAG EQ CONSOLE 
&READ ARGS 



-FINIS 
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In this EXEC procedure, the statements following the label -SETUP stack 
a number of lines. The variables SNUM and SCHAR are substituted before 
they are stacked. At the label -READ, the lines are read in from the 
stack and processed. The values stacked are read in as the variable 
symbols S1 and &2. Control passes out of the loop when the stack is 
empty. 



CLEARING THE CONSOLE STACK 

If you use the console stack in an EXEC procedure, you should be sure 
that it is empty before you begin stacking lines in it. Also, you 
should be sure that it is empty before exiting from the EXEC (unless you 
have purposely stacked CMS commands for execution) . 

One way to clear a line from the stack without affecting the 
execution of your EXEC is to use the &READ VARS or SREAD ARGS control 
statement. You can use SREAD VARS without specifying any variable 
symbols so that the line read is read in and effectively ignored. For 
example: 

&LOOP 1 8READFLAG EQ CONSOLE 
&READ VARS 

If these lines occur at the beginning of an EXEC file, they ensure that 
any stacked lines are cleared. If the EXEC is named EXEC1 and is 
invoked with the line: 

exec1#type help memc#type print memo 

then the lines TYPE HELP MEMO and TYPE PRINT MEMO are cleared frcm the 
stack and are not executed. 

You could use the same technique to clear the stack in case of an 
error encountered in your EXEC, so that the stack is cleared before 
returning to CMS. You would especially want to do this if you stacked 
data lines or EXEC control statements that have no meaning to CMS. 

Another way to clear the console stack is with the CMS function 
DESBDF. For example, 

SIF 8READFLAG EQ STACK DESBUF 

When you use the DESBUF function to clear the console input stack, the 
output stack is also cleared. The output stack contains lines that are 
waiting to be displayed or typed at the terminal. Frequently, when an 
EXEC is processing, output lines are stacked, and are not displayed 
immediately following the execution of an 8TYPE statement. If you want 
to display all pending output lines before clearing the console input 
stack, you should use the CONWAIT function, as follows: 

CONWAIT 

&IF &READFLAG EQ STACK DESBUF 

The CONWAIT (console wait) function causes a suspension of program 
execution until the console output stack is empty. If there are no lines 
waiting to be displayed, CONWAIT has no effect. 

Clearing the stack is important when you write edit macros, since all 
subcommands issued in an edit macro must be first stacked. See "Section 
17. Writing Edit Macros" for additional information on using the console 
stack. 
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File Manipulation with EXECs 

You can, to a limited degree, read and write CNS disk files using EXECs. 
You can stack files with a filetype of EXEC in the console stack and 
then read them, one record at a time, with &READ control statements. All 
data items are truncated to 8 characters. You can write a file, one 
record at a time, with the SPUNCH control statement, and then you can 
read the spool punch file onto disk. Examples of these techniques 
follow. 



STACKING EXEC FILES 

There are two methods to stack EXEC files in the console stack. One is 
illustrated using a CMS EXEC file, as shown in the following PREFIX 
EXEC: 

&LNAME = &CONCAT £1 * 

LISTFILE SLNAME SCRIPT * (EXEC 

EXEC CMS &STACK 

SLOOP -EHD SREADFLAG EQ CONSOLE 

BREAD VARS SNAME STYPE &MOD 

SSUFFIX = SSUBSTR &NAME 3 5 

&NEWNAM = &CONCAT 62 SSUFFIX 

RENAME SHAME STYPE &MOD &NEWNAM &TYPE &MOD 

&IF &RETCODE EQ &SKIP 

STYPE FILE &NAME STYPE NOT RENAMED 

-END 

This EXEC procedure is invoked with two arguments, each 2 characters in 
length, which indicate old and new prefixes for filenames. The EXEC 
renames files with a filetype of SCRIPT that have the first prefix, 
changing only the prefix in the filename. 

The LISTFILE command, invoked with the EXEC option, creates a CMS 
EXEC file in the format: 

&1 82 filename SCRIPT mode 

When the EXEC is invoked with the line 

EXEC CMS SSTACK 

the argument &STACK is substituted for the variable symbol &1 in each 
line in the CMS EXEC. The execution of the CMS EXEC effectively stacks, 
in the console stack, the complete file identifications of the files 
listed : 

SSTACK filename SCRIPT mode 
SSTACK filename SCRIPT mode 



These stacked lines are read back into the EXEC, one at a time, and the 
tokens "filename", "SCRIPT", and "mode" are substituted for the variable 
symbols &NAME, STYPE, and SHOD. 

Using the &SUBSTR and SCONCAT built-in functions, the new name for 
each file is constructed, and the RENAME command is issued to rename the 
files. 
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For example, if you invoke the EXEC procedure with the line 

prefix afc xy 

all SCRIPT files that have filenames beginning with the characters AB 
are renamed so that the first two characters of the filename are XY. A 
sample execution summary of this EXEC is illustrated under "Debugging 
EXEC Procedures" in "Section 16. Refining Your EXEC Procedures." 

Stacking Data Files 

You can create a data file, containing fixed-length records, using a 
filetype of EXEC. To stack these data lines in the console stack, you 
can enter them following an &BEGSTACK (or &BEGSTACK ALL) control 
statement. For example, the file DATA EXEC is as follows: 

SBEGSTACK 
HARRY 10/12/48 
PATTI 1/18/49 
DAVID 5/20/70 
KATHY 8/6/43 
MARVIN 2/28/50 

The file BDAY EXEC contains: 

&CONTROL ERROR 

EXEC DATA 

SIF &READFLAG EQ CONSOLE &G0T0 -NO 

BREAD VARS &NAME &DATE 

SIF &NAME NE &1 &SKIP -2 

-FOUND 

SIF .&1 EQ . &EXIT 

STYPE 61 «S BIRTHDAY IS SDATE 

CONWAIT 

DESBUF 

SEX IT 

-NO 6TYPE &1 NOT IN LIST 

&EXIT 

When the BDAY EXEC is invoked, it expects an argument that is a first 
name. The function of the EXEC is to display the birthday of the 
specified person. A sample execution of this EXEC might be: 

bday kathy 

KATHY «S BIRTHDAY IS 8/6/43 

R; 



BDAY EXEC first executes the 
in the console stack. Then, BDAY 
stack, assigning the variable n 



DATA EXEC, which stacks names and dates 

EXEC reads one line at a time from the 

ames &NAHE and &DATE to the tokens on 



each line. It compares &NAHE with the argument read as 81. When it finds 
a match, it displays the message indicating the date, and clears the 
console stack after waiting for terminal output to finish. 

Note that the file DATA EXEC begins with an SBEGSTACK control 
statement, but contains no SEND statement. The stack is terminated by 
the end of the EXEC file. "Writing Data Files" describes a technigue 
you might use to add new names and birth dates to the DATA EXEC file. 
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Writ ±no[ Data Files 

You can build a CMS file in your virtual card punch using the &PUNCH and 
BBEGPUNCH control statements. Depending on the spooling characteristics 
of your virtual punch, the file that you build may be sent to another 
user's card reader, or to your own virtual card reader. When you read 
the file with the CMS READCARD command, the spool reader file becomes a 
CMS disk file. 

The following example illustrates how you might use your card punch 
and reader to update a CMS file by adding records to the end of it. The 
file being updated is the DATA EXEC, which is the input file for the 
BDAY EXEC, shown in the example in "Stacking Data Files. " You could 
create a separate EXEC to perform the update, but this example shows how 
you might modify the BDAY EXEC to perform the addition function 
(ellipses indicate the body of the EXEC, which is unchanged) : 

&CONTROL ERROR 

6IF 81 EQ ADD &GOTO -ADDNAME 



SEXIT 

-ADDNAME 

6TYPE ENTER FIRST NAME AND DATE IN FORM MM/DD/YY 

SREAD VARS &NAME &DATE 

SIF .SHAME = . SSKIP 3 

&PUNCH &NAME &DATE 

®I!YPE ENTER NEXT NAME OR NULL LINE: 

&SKIP -4 

CP SPOOL PUNCH TO * 

CP CLOSE PUNCH 

READCARD NEW NAMES 

COPYFILE NEW NAMES A DATA EXEC A (APPEND 

SIF SRETCODE = &SKIP 2 

&TYPE ERROR CREATING FILE 

SEXIT SRETCODE 

ERASE NEW NAMES 

When BDAY EXEC is invoked with the keyword ADD, you are prompted to 
enter lines to be added to the data file. Each line that you enter is 
punched to the card punch. When you enter a null line, indicating that 
you have finished entering lines, the CP commands SPOOL and CLOSE direct 
the spool file to your card reader and close the punch. 

The file is read in as the file NEW NAMES, which is appended to the 
file DATA EXEC using the COPYFILE command with the APPEND option. The 
file NEW NAMES is erased and the EXEC terminates processing. 

Ising Your Virtual Card Punch 

When you punch lines in your virtual punch, the lines are not released 
as a CP spool file until the punch is closed. Since the EXEC processor 
does not close the virtual punch when it terminates processing, you must 
issue the CLOSE command to release the file. You can do this in the EXEC 
with the command line 

CP CLOSE PUNCH 

or from the CMS environment after the EXEC has finished. If you use the 
CLOSE command in the EXEC, you must preface it with CP. 
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The CMS PUNCH command, which you can use in an EXEC to punch an 
entire CMS file, does close the punch after punching a file. Therefore, 
if you want to create a punch file using a combination of &PUNCH control 
statements and PUNCH commands, you must spool your punch using the CONT 
option, so that a close request does not affect the file: 

' CP SPOOL PUNCH TO * CONT 
SPUNCH FIRST FILE 
&PUNCH 

PUNCH FILE1 TEST ( NOHEADER 
&PUNCH SECOND FILE 
SPUNCH 

PUNCH FILE2 TEST ( NOHEADER 
CP SPOOL PUNCH CLOSE NOCONT 

The preceding example punches title lines introducing the files punched 
with the CMS PUNCH command. The null SPUNCH statements punch blank 
lines. The PUNCH command is issued with the NOHEADER option, so that a 
read control card is not punched. 

You can also use an EXEC procedure to punch a job to send to the CMS 

Batch Facility for processing. The batch facility, and an example of 

using an EXEC to punch a job to it, are described in "Section 12. Using 
the CMS Batch Facility." 

Using SPUNCH and &BEGPUNCH 

All lines punched to the virtual card punch are fixed-length, 
80-character records. When you use the &PUNCH control statement in a 
fixed-length EXEC file, EXEC scans only the first 72 columns of the 
EXEC. 

If you want to punch a word that contains more than 8 characters, you 
must use the &BEGPUNCH control statement, which also, in fixed- length 
files, causes EXEC to punch data in columns 1 through 80. 
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Whenever you create an EXEC file you are, for all practical purposes, 
creating a new CMS command. When you enter a command line in the CMS 
environment, CMS searches for an EXEC file with the specified filename 
before searching for a MODULE file or CMS command. You can place the 
names of your EXEC files in a synonym table and assign minimum 
truncation values for the synonyms, just as you can for CMS command 
names. 

While many of your EXEC procedures may be very simple, others may be 
very long and complicated, and perform many of the housekeeping 
functions performed by CMS commands, such as syntax checking, error 
message generation, and so on. 



Monitoring CMS Command Execution 

Many, or most, of your EXEC procedures may contain sequences of CMS 
commands that you want to execute. If your EXEC procedure contains no 
EXEC control statements, each command line is displayed and then the 
command is executed. If an error occurred, the CMS error message is 
displayed, followed by a return code in the format: 

+++ B(nnnnn) +++ 

where nnnnn is the nonzero return code from the CMS command. If the 
command is not a valid CMS command, the return code is a -3: 

+++ R(-0003) +++ 

You may also receive this error return when you use a CP command without 
prefacing it with the CP command. If you enter an unknown CP command 
following "CP", you receive a return code of 1. 

If a command completes successfully, no return code is displayed. 

If you do not want to see the command lines displayed before 
execution, nor return codes following execution, you can use the EXEC 
control statement: 

SCONTROL OFF 

Or, if you want to see only the command lines that produced errors, and 
the resultant return codes, you can specify: 

SCONTROL ERROR 

Regardless of these settings of the SCONTROL statement, CMS error 
messages are displayed, as long as the value of SREADFLAG is RT, and the 
terminal is displaying output. 

If you issue the LISTFILE, STATE, ERASE, or RENAME commands in an 
EXEC procedure, and you do not want to see the error message FILE N3T 
FODNE displayed, you can use the statement: 

SCONTROL NOMSG 

to suppress the display of these particular messages. 
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You can request that particular timing information be displayed 
during an EXEC's execution. If you want to display the time of day at 
which each command executes, you can specify 

&CONTROL TIME 

Then, as each command line is displayed, it is prefaced with the time, 
for example, 

SCONTROL CMS TIME 
QUERY BLIP 

executes as follows: 

10:34: 16 QUERY BLIP 
BLIP = * 

If you wish to see, following the execution of each CMS command, 
specific CPU timing information, such as the long form of the Ready 
message, you can use the &TIME control statement. For example, 

8TIME CN 
QUERY BLIP 
QUERY FILEDEF 

might execute as: 

QUERY BLIP 
BLIP = OFF 
T=0.01/0.04 10:44:21 

QUERY FILEDEF 

NO USER DEFINED FILEDEF'S IN EFFECT 

T=0.01/0.04 10:45:26 



Handling Error Returns From CMS Commands 

In many cases, you want to execute a command only if previous commands 
were successful. For example, you would not want to execute a PRINT 
command to print a file if you had been unable to access the disk on 
which the file resided. There are two methods, using EXEC procedures, 
that allow you to monitor and control what happens following the 
execution of CMS commands. One method uses the EXEC control statement 
&ERRCR to transfer control when an error occurs; the other tests the 
special variable &RETCODE upon completion of a CMS command to determine 
whether that particular command completed successfully. 

USING THE &ERROR CONTROL STATEMENT 

When a CMS command is executed within an EXEC, a return code is passed 
to the EXEC interpreter, indicating whether or not the command completed 
successfully. If the return code is nonzero, EXEC then activates the 
&ERROR control statement currently in effect. For example, if the 
following statement is included at the beginning of an EXEC file 

&ERR0R &EXIT 

then, whenever a CMS command (or user program) completes with a nonzero 
return code, the SEXIT statement in the 8ERR0R statement is executed, 
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and the EXEC terminates processing. You might use a similar statement 
in your EXECs to ensure that they do not attempt to continue processing 
in the event of an error. 

An SERROR control statement can specify any executable statement. It 
may transfer control to another portion of the EXEC, or it many be a 
single statement that executes before control is returned to the next 
statement in the EXEC. For example, 

&ERROR &GOTO -EXIT 

transfers control to the label -EXIT, in case of any CMS error. The 
statement 

SERROR 6TYPE CMS ERBOR 

results in the display of the message "CMS ERROB" before returning 
control to the statement following the command that caused the error. 

If you do not have an SERROR control statement in an EXEC, or if you 
specify SEREOB with no operands, EXEC takes no special action when a CMS 
command returns with an error return code. Specifying &EBROR with no 
operands is the same as specifying: 

SERROR &CONTINUE 

Since an SERROR control statement remains in effect for the remainder 
of the EXEC execution, or until another SERROR control statement is 
encountered, you may use SERROR &CONTINUE to restore default 
processing. 



USING THE SRETCODE SPECIAL VARIAELE 

An error return from a CMS command, in addition to calling an SERROR 
control statement, also places the return code value in the EXEC special 
variable SRETCODE. Following the execution of any CMS command in an 
EXEC procedure, you can test whether or not the command completed 
without error. For example, 

TYPE ALPHA FILE A 

SIF SRETCODE -.= SEXIT 

TYPE BETA FILE A 

SIF SRETCODE -.= SEXIT 

Bote that the value of SRETCODE is modified after the execution of each 
CMS command. 

The value of SRETCODE is affected by your own programs. If you 
execute a program in your EXEC using the LOAD and START (or FETCH and 
START) commands, or if you execute a MODULE file, then the SRETCODE 
special variable contains whatever value was in general register 15 when 
the program exited. If you are nesting EXEC procedures, then SRETCODE 
contains the value passed from the SEXIT statement of the nested EXEC. 

You can use the value of the return code, as well, to analyze the 
extent or the cause of the error, and set up an error analysis routine 
accordingly. For example, suppose you want to set up an analysis 
routine to identify return codes 1 through 11, and to exit from the EXEC 
when the return code is greater than 11. When a return code is 
identified, control is passed to a corresponding routine that attempts 
to correct the error. You could set up such an analysis routine as 
follows: 
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-ERRANAL 

&CNT = 

SLOOP 2 6CNT EQ 12 

&IF &RETCODE EQ &CNT 8G0T0 -FIXSCNT 

&CNT*= 8CNT + 1 



-FIXO fiGOTO -ALLOK 
-FIX1 



&GOTO -ALLOK 
-FIX2 



8G0T0 -ALLOK 



-FIX 11 



-ALLOK 



When the value of the &CNT variable equals the return code value in 
&RETCODE, the branch to the corresponding -FIX routine is taken. Each 
corrective routine performs different actions, depending on its code, 
and finishes at the routine labeled -ALLOK. 

You can, in some cases, determine the cause of a CMS command error 

and attempt to correct it in your EXEC. To do this, you must know the 

return codes issued by VM/370 commands. See VM^370: System Messages for 

a discussion of the return codes for VM/370 commands. In addition, the 

error messages and corresponding return codes are listed under the 

command descriptions for each CMS command in the VM^370: CMS Command and 
H§££2 Mf §£§!£§ • 

As an example, all CMS commands that search for files issue a return 
code of 28 when a file is not found. If you want to test for a file not 
found condition in your EXEC, you might use statements similar to the 
following: 

SCONTROL OFF NOMSG 



TYPE HELP MEMO A 

&IF SRETCODE = 28 &GOTO -NOFILE 



Tailoring CMS Commands for Your Own Use 

You can create EXEC procedures that simplify or extend the use of a 
particular CMS command. Depending on your applications, you can modify 
the CMS command language to suit your needs. You can create EXEC files 
that have the same names as CMS commands, and, since CMS locates EXEC 
files before MODULE files, the IXIC is found first. For example, the 
COPYFILE command, when used to copy CMS disk files, requires six 
operands. If you change only the filename when you copy files, you could 
create a COPY EXEC as follows: 

288 IBM VM/370: CMS User's Guide 



8C0NTR0L OFF 

6IF &INDEX --= 3 &SKIP 

COPYFIIE &1 62 = 63 82 = 

COPYFILE &1 82 &3 64 65 66 67 68 69 610 611 612 613 614 615 

If you always invoke the COPYFILE command using the truncation COPY, 
EXEC processes the command line for you, and if you have entered the 
three arguments, EXEC formats the COPYFILE command for you. If any 
other number of arguments are entered, the COPYFILE command is invoked 
with all the arguments as entered. 

CREATING YOUR OWN DEFAULT FILETYPES 

If you use special filetypes for particular applications and they are 
not among those that the CMS Editor supplies default settings for, but 
do reguire special editor settings, you can create an EXEC to invoke the 
editor. The EXEC can check for particular filetypes, and if it finds 
them, stack the appropriate EDIT subcommands. If you name this EXEC 
procedure E EXEC # then you can bypass it using a longer form of the EDIT 
command. The following is a sample E EXEC: 

6C0NTR0L OFF 

8IF 8INDEX GT 1 6SKIP 2 

EDIT 61 SCRIPT 

6EXIT 

&IF 62 EQ TABLE &GOTO -TABLE 

6IF 62 EQ CHART &GOTO -CHART 

6IF 62 EQ EXEC 6G0T0 -EX 

6IF 62 EQ SYSIN 6G0T0 -SYSIN 

-NORM EDIT 61 62 63 64 65 66 

6EXIT 

-TABLE &BEGSTACK 

IMAGE ON 

TABS 1 10 20 

CASE M 

&END 

EDIT 81 82 63 (LRECL 20 

6 EX IT 

-CHART 8BEGSTACK 

CASE M 

IMAGE ON 

6END 

EDIT 61 62 83 

&EXIT 

-EX 

EDIT 61 62 63 (LRECL 130 

8EXIT 

-SYSIN 6BEGSTACK 

TABS 1 10 16 31 36 41 46 69 72 80 

SERIAL ON 

TRUNC 71 

VERIFY 72 

&END 

EDIT 61 62 63 

8EXIT 

This EXEC defines special characteristics for filetypes CHART, TABLE, 
and SYSIN, and defaults an EXEC file to 130-character records. If only 
one argument is entered, it is assumed to be the filename of a SCRIPT 
file. Since the editor is invoked from within the EXEC, control returns 
to EXEC after you use the FILE or QUIT subcommands during the edit 
session, and you must use the &EXIT control statement so that the EXEC 
does not continue processing, and execute the next EDIT command in the 
file. 
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This section provides supplementary information for writing complex £XEC 
procedures. Although the EXEC interpreter resembles, in some aspects, a 
high-level programming language, you do not need to be a programmer to 
write EXECs. some of the technigues suggested here, for example, on 
annotating and writing error messages, are common programming practices, 
which help make programs self-documenting and easier to read and to 
use. 



Annotating EXEC Procedures 

Lines in an EXEC file that begin with an asterisk (*) are not processed 
by the EXEC interpreter. You can use * statements to annotate your 
EXECs. If you write EXECs freguently you may find it convenient to 
include a standard comment at the beginning of each EXEC, indicating its 
function and the date it was written, for example: 

* EXEC TO HELP CONVERT LISTING FILES 

* INTO SCRIPT FILES 

* J. BEAN 10/18/75 

You can also use single asterisks or null lines to provide spacing 
between lines in an EXEC file to make examining the file easier. 

In an EXEC, you cannot place comments on the same line with an 
executable statement. If you want to annotate a particular statement or 
group of statements, you must place the comments either above or below 
the lines you are annotating. 

A good practice to use, when writing EXECs, is to set them up to 
respond to a ? (guest ion mark) entered as the sole argument. For 
example, an EXEC named FSORT might contain: 

&C0NTR0L OFF 

8IF SIMDEX = 1 &IF £1 = ? &GOTO -TELL 



-TELL 8BEGTYPE 

CORRECT FORM IS • FSORT USERID <VADDR> • 

PRINTS AN ALPHABETIC LISTING OF ALL FILES ON THE SPECIFIED 
USER'S DISK. IF A VIRTUAL ADDRESS (VADDR) IS NOT 
SPECIFIED, THE USER'S 191 IS THE DEFAULT. 
SEND 

You may also wish to anticipate the situation in which a user might 
enter an EXEC name with no arguments, for an EXEC that reguires 
arguments: 
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6IF SINDEX = SGOTO -HELP 

&IF &INDEX = 1 6IF S1 = ? &GOTO -TELL 



&EXIT 

-HELP SBEGTYPE 

CORRECT FORM IS • COPY OLDFN OLDFT NEWFN • 

TYPE • COPY ? • FOR MORE INFO 
SEND 
SEXIT 
-TELL SBEGTYPE 

CORRECT FORM IS • COPY OLDFN OLDFT NEWFN • 

USES COPYFILE COMMAND TO CHANGE ONLY THE FILENAME 
SEND 
SEX IT 

This type of annotating is especially useful if you share your disks or 
your EXECs with other users. 



Error Situations 

It is good practice, when writing EXECs, to anticipate error situations 
and to provide meaningful error or information messages to describe the 
error when it occurs. The following error situations, and suggestions 
for handling them, have already been discussed: 

• Errors in invoking the EXEC, either with an improper number of 
arguments, or with invalid arguments. (See "Arguments" in "Section 
14. Building EXEC Procedures.") 

• Errors in CMS command processing that can be detected with an SERROR 
control statement or with the SRETCODE special variable. (See 
"Handling Error Returns from CMS Commands" in "Section 15. Using 
EXECs With CMS Commands.") 

Many different kinds of errors may occur, also, in the processing of 
your EXEC control statements. EXEC processing errors, such as an attempt 
to branch to a nonexistent label, or an invalid syntax, are 
"unrecoverable" errors. These errors always terminate EXEC processing 
and return your virtual machine to the CMS environment, or to the 
calling EXEC procedure or program. The error messages produced by EXEC, 
and the associated return codes, are described in the VM£370: System 
Messages . 



WRITING ERROR MESSAGES 

One way to make your EXECs more readable, especially if they are long 
EXECs, is to group all of your error messages in one place, probably at 
the end of the EXEC file. You may also wish to number your messages and 
associate the message number with a label number and a return code. For 
example: 
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SIF SCT > 100 &GOTO -ERR 100 
SIF SCT < SGOTO -FRR200 



6IF SRETCODE EQ 28 SGOTO -ERR300 



-ERR100 

STYPE COUNT TOO HIGH 

SEXIT 100 

-ERR200 

STYPE COUNT TOO LOW 

SEXIT 200 

-ERR300 

STYPE &1 62 NOT ON DISK • C« . 

SEXIT 300 

Hsin<j the &EMSG Control Statement 

There is a facility available in the EXEC processor, which allows you to 
write error messages that use the standard VM/370 message format, with 
an identification code and message number, as well as message text. 
When you use the &EMSG or SBEGEMSG control statement, the EXEC 
interpreter scans the first token and checks to see if the seventh (and 
last character) is an I, E, or W, representing information, error, or 
warning messages, respectively. If so, then the message is displayed 
according to the CP EMSG setting (ON, OFF, CODE, or TEXT) . For example, 
if you have the statement 

SEMSG ERR0R1E BAD ARGUMENT • &1 • 

the ERR0R1E is considered the code portion of the message and BAD 
ARGUMENT is the text. If you have issued the CP command 

cp set emsg text 

when this SEMSG statement is executed it may display 

BAD ARGUMENT • PRNIT • 

where PRNIT is the argument that is invalid. 

When you use SEMSG (or SBEGEMSG, which allows you to display error 
messages of unscanned data) , the code portion of the message is prefixed 
with the characters DMS, when displayed. For example 

SBEGEMSG 

ERROR2E INCOMPATIBLE ARGUMENTS 

SEND 

displays, when the EMSG setting is ON, 

DMSERROR2E INCOMPATIBLE ARGUMENTS 

You should use the SBEGEMSG control statement when you want to display 
lines that have tokens longer than 8 characters; however, no variable 
substitution is performed. 
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Debugging EXEC Procedures 

If you have difficulty getting an EXEC procedure to execute properly, cr 
if you are modifying an existing EXEC and wish to test it, there are a 
couple of simple technigues that you can use that may save you time. 

One is to place the &CONTROL ALL control statement at the top of your 
EXEC file. When &C0NTB0L ALL is in effect, all the EXEC control 
statements are displayed before they execute, as well as the CMS command 
lines. One of the advantages of using this method is that the line is 
displayed after it is scanned, so that you can see the results of symbol 
and variable substitution. 

"Stacking EXEC Files" in "Section 14. Building EXEC Procedures" 
described a PREFIX EXEC, which changes the prefixes of groups of files. 
If the EXEC had an &CONTROL ALL statement, it might execute as follows: 

prefix pt ag 

&CONTROL ALL 

&LNAME = &CONCAT PT * 

LISTFILE PT* SCRIPT * ( EXEC 

EXEC CMS &STACK 

&LOOP -END &READFLA EQ CONSOLE 

LOOP UNTIL: STAC K EQ CONS 

&READ VARS &NAME 6TYPE SMOD 

8SUFFIX = &SOBSTR PTA 3 5 

&NEWNAM = &CONCAT AG A 

RENAME PTA SCRIPT A1 AGA SCRIPT A1 

&IF EQ SSKIP 

&SKIP 

LOOP UNTIL: STAC K EQ CONS 

SREAD VARS &NAME &TYPE &MOD 

&SUFFIX = &SUBSTR PTB 3 5 

&NEWNAM = 6C0NCAT AG B 

RENAME PTB SCRIPT A1 AGB SCRIPT A1 

SIF EQ SSKIP 

&SKIP 

LOOP UNTIL: CONS OLE EQ CONS 

R; 

You can see from this execution summary that the files named PTA SCRIPT 
and PTB SCRIPT are renamed to AGA SCRIPT and AGB SCRIPT. Notice that 
the SLOOP statement results in a special LOOP UNTIL statement in the 
execution summary, which indicates the condition under which the loop 
executes. 



USING CMS SUBSET 

When you are using the CMS Editor to create or modify an EXEC procedure, 
you can test the EXEC in the CMS subset environment, as long as the EXEC 
does not issue any CMS commands that are invalid in CMS subset. 

Before entering CMS subset with the CMS subcommand, you must issue 
the SAVE subcommand to write the current version of the EXEC onto disk; 
then, in CMS subset, execute the EXEC. For example: 
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edit new exec 

NEW FILE: 

EDIT: 

input 

INPUT: 

&a = &1 + &2 + &3 

Stype answer is &a 

EDIT: 

save 

EDIT: 

cms 

CMS SUBSET 

new 34 56 899 

ANSWER IS 989 

R; 

return 

EDIT: 

quit 

R; 

If the EXEC does not execute properly, you can return to the edit 
environment using the RETURN command, modify the EXEC, reissue the SAVE 
and CMS subcommands, and attempt to execute the EXEC again. 



SUMMARY OF EXEC INTERPRETER LOGIC 

The following information is provided for those who have an interest in 
how the EXEC interpreter works. It may help you in debugging your EXEC 
procedures if you have some idea of how processing is done by EXEC. 
When an EXEC file is invoked for execution, the EXEC interpreter 
examines each statement and analyzes it, according to the following 
sequence: 

1. If the first nonblank character of the line is an * , the line is 
ignored. 

2. Null lines, except as a reponse to an &READ statement, are also 
ignored. 

3. The line is scanned, and nonl ik character strings are placed in 
tokens. 

4. All EXEC special variables, ani_£hen all user variables, except for 
those that appear as the target of an assignment statement, are 
substituted. 

6. All blank tokens (resulting from the substitution of undefined 
symbols) are discarded. 

7. If the first nonblank character is a hyphen (-) , indicating a 
label, the next token is considered the first token. 

8. If the first logical token does not begin with an ampersand (&) , 
the line is passed to CMS for execution. The return code from CMS 
is placed in the special variable &RETCODE. 

9. If the first logical token begins with an ampersand (&) EXEC 
interprets the statement. 

10. If a statement is syntactically invalid and can be made valid by 
adding a token of blanks at the end, EXEC adds blanks, for example: 
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&BLANK = 

STYPE 

SLOOP 3 SX NE 

All of the above are valid EXEC control statements. 

11. EXEC executes the statement. If no error is encountered, control 
passes to the next logical statement. If an error is encountered, 
EXEC terminates processing. 
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Section 17. Writing Edit Macros 



If you have a good knowledge of the CMS EXEC facilities, and an 
understanding of the CHS Editor, you may wish to write edit macros. In 
edit macro is simply an EXEC file that contains a sequence of EDIT 
subcommands. Edit macros can only be invoked from the edit environment. 
An edit macro may contain a simple sequence of EDIT subcommands, or its 
execution may be dependent on arguments you enter when you invoke it. 
This section provides information on creating edit macros, suggestions 
on how to manipulate the console stack, and some examples of macros that 
you can create and use. 



Creating Edit Macro Files 

An edit macro must have a filename beginning with a dollar sign ($) and 
a filetype of EXEC. Rules for file format, scanning and token 
substitution are the same as for all other EXEC files. A macro file may 
contain: 

• EDIT subcommands 

• EXEC control statements 

• CHS commands that are valid in CHS subset 

When you create an edit macro that accepts arguments, you should be 
sure to check the validity of the arguments, and issue appropriate error 
messages. If you are writing an edit macro to expect arguments, you must 
keep in mind that the macro command line is scanned, and that any data 
items you enter are padded or truncated into 8-character tokens. Tokens 
are always translated to uppercase letters. 

You should annotate all of your macro files, and provide a response 

to a question mark (?) entered as the sole argument (as described under 

"Annotating EXEC Procedures" in "Section 16. Refining Your EXEC 
Procedures." 



How Edit Macros Work 

Since an edit macro is an EXEC file, it is actually executed by the EXEC 
interpreter, and not by the editor. The EXEC interpreter can only 
execute EXEC control statements and CHS commands. The only way to issue 
an EDIT subcommand from an EXEC file is to stack the subcommand in the 
console stack, so that when the editor is invoked, or receives control, 
it reads the subcommand (s) from the console stack before accepting input 
lines from the terminal. For example: 

SSTACK CASE H 
©STACK RECFH V 
EDIT £1 CHART A1 

When the EDIT command is invoked from this EXEC, the editor reads the 
subcommands from the stack and executes them. 

To execute these same subcommands from an edit macro file, you must 
use the same technique; that is, you must place the subcommands in the 
console stack, for example: 
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SBEGSTACK 
CASE M 
RECFM V 
SEND 
8EXIT 

If this were an EXEC file named $VARY, you might execute it from the 
edit environment as follows: 

edit test file 
NEW FILE. 
EDIT: 
$vary 

Stacked subcommands are executed only when the EXEC completes its 
execution, either by reaching the end of the file, or by processing an 
8EXIT statement. 

when you stack edit subcommands, you can use the SSTACK and SBEGSTACK 
control statements. If you are stacking a subcommand that uses a 
variable expression, you must use the SSTACK control statement, rather 
than the SBEGSTACK control statement. The following EXEC, named $T, 
displays a variable number of lines and then restores the current line 
pointer to the position it was in when the EXEC was invoked: 

SCONTRCL OFF 

SIF SINDEX EQ SGOTO -ERR 

SCHECK = SDATATYPE 81 

&IF SCHECK NE NUM SGOTO -ERR 

SSTACK TYPE 81 

SUP = S1 - 1 

SSTACK UP SUP 

SEXIT 

-ERR 8TYPE CORRECT FORM IS < $T N > 

SEXIT 1 

This edit macro uses the built-in function SDATATYPE to check that a 
numeric operand is entered. 

CHS commands in an edit macro are executed as they are read by the 
EXEC interpreter, just as they would if the EXEC were invoked in the CMS 
environment. You could create a $TYPE edit macro, for example, that 
would allow you to display a file from the edit environment: 

SCONTROL OFF 

TYPE 81 82 63 &4 65 86 67 

Or you might create a SSTATE EXEC that would verify the existence of 
another file: 

SCOSTROL OFF 
STATE &1 &2 63 

In both of these examples, the macro file invokes the CMS command. 
Macros like these can eliminate having to enter CMS subset environment 
to execute one or two simple CMS commands. You must be careful, though, 
not to execute any CMS command that uses the storage occupied by the 
editor. Only commands that are valid in CMS subset are valid in an edit 
■aero. 
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THE CONSOLE STACK 

Hhen you write an edit macro, you want to be sure that there are no EDIT 
subcommands in the stack that could interfere with the execution of the 
subcommands stacked by the macro file. Your macro should check whether 
there are any lines in the stack, and if there are, it should clear them 
from the stack. For example, you might use the lines: 

SIF SREADFLAG EQ CONSOLE SSKIP 2 

DESBUF 

STYPE STACKED LINES CLEARED BY 60 

The message "STACKED LINES CLEARED BY macro name" is issued by the edit 
macros distributed with the VM/370 system. You may also want to use 
this convention in your macros, to alert a user that the console stack 
has been cleared. 

Hhen an edit macro is invoked and the current line pointer is positioned 
at the top of the file or at the end of the file, the editor stacks a 
token in the console stack. If the line pointer is at the top cf the 
file, the token stacked is "TOF" ; if the line pointer is at the end of 
the file the token stacked is ♦•EOF". If you write an edit macro that 
does not check the status of the console stack, and the macro is invoked 
from the top or the end of the file, you receive the message 

?EDIT: TOF 
or: 

?EDIT: EOF 

The editor does not recognize these tokens as valid subcommands. 

You may want to use these tokens to test whether the EXEC is invoked 
from the top or end of the file. If you want to clear these tokens in 
case the macro has been invoked from the top or end of the file, you 
might use the statement: 

SIF SREADFLAG EC CONSOLE SREAD VARS 

which clears the token from the stack. 

If you do not want to clear the console stack when you execute an edit 
macro, you can stack all of the subcommands using the LIFO (last-in 
first-out) operand of the SSTACK and &BEGSTACK control statements: 

SBEGSTACK LIFO 
TABSET 3 10 71 
TRONC 71 
PRESERVE 
SEND 
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When this edit macro is executed, the subcommands are placed in the 
console stack in front of any existing lines. For example, if this macro 
were invoked 

$format#input 

the subcommands would execute in the following order: PRESERVE, TRUNC, 
TABSET, INPUT. If the subcommands were stacked FIFO (first-in 
first-out) , the default, the INPUT subcommand would be the first to 
execute (since it is the first command in the stack) and the remaining 
subcommands would be read into the file as input lines. 

I.E£5i Situations 

If an EXEC processing error occurs during the execution of an edit 

macro, the editor clears the console stack and issues the "STACKED LINES 

CLEARED" message. An EXEC processing error is one that causes the error 
message DMSEXT072E: 

ERROR IN EXEC FILE filename, LINE nnnn - description 

These errors cause the EXEC interpreter to terminate processing. Any 
stacked subcommands are cleared before the editor regains control, so 
that none of the subcommands are executed, and the file remains 
unchanged. 

You should also ensure that any error handling routines in your edit 
macros clear the stack if an error occurs, otherwise, the editor may 
begin reading invalid data lines from the stack and attempt to execute 
them as EDIT subcommands. 

You should not interrupt the execution of an edit macro by using the 
Attention or Enter key, and then entering a command or data line. 
Results are unpredictable, and you may inadvertently place unwanted 
lines in the stack. 

If your edit macro contains a CMS command that is invalid in the CMS 
subset environment, you receive a return code of -2. 

The maximum number of lines that you can stack in an edit macro 
varies according to the amount of free storage that is available to CMS 
at the time of the stacking reguest. If you stack tco many lines, the 
editor terminates abnormally. 



Notes on Using EDIT Subcommands 

You can use any EDIT subcommand in a macro file, and there is one 
special subcommand whose use only has meaning in a macro: the STACK 
subcommand. For the most part, there is not any difference between 
executing an EDIT subcommand from the edit environment, or from an EXEC 
edit macro. You do have to remember, however, that if you want a 
variable symbol on a subcommand line, you must stack that subcommand 
using the SSTACK control statement rather than following an SBEGSTACK 
control statement. 

Listed below are some notes on using various EDIT subcommands in your 
macro files. You may find these notes useful when you design your own 
macros. 
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PRESERVE, VERIFY, AND RESTORE: Often, you may want to create an edit 
macro that alters the characteristics of a file (format, tab settings, 
and so on) . To ensure that the original characteristics are retained 
when the macro has finished executing, you can stack the PRESERVE 
subcommand as the first subcommand in the stack, and the RESTORE 
subcommand as the last subcommand in the stack: 

SBEGSTACK 

PRESERVE 

CASE M 

I A lowercase line 

RESTORE 

SEND 

The PRESERVE and RESTORE subcommands save and reinitialize the settings 
for the CASE, FMODE, FNAME, IMAGE, LINEMODE, LONG, RECFM, SERIAL, SHORT, 
TABSET, TRUNC, VERIFY, and ZONE subcommands. 

In an edit macro that issues many subcommands that display lines in 
response to CHANGE or LOCATE subcommands, you may want to turn the 
verification setting to OFF to suppress displays during the execution of 
the edit macro: 

&BEGSTACK 
PRESERVE 
VERIFY OFF 



RESTORE 
SEND 

You would particularly want to turn verification off for a macro that 
executes in a loop, or that issues a global reguest. If you want a line 
or series of lines displayed, you can use the TYPE subcommand. 

If you have verification set off in an edit macro, then when you 
execute it you may not receive any indication that the edit macro 
completed execution. The keyboard unlocks to accept your next EDIT 
subcommand from the terminal. To indicate that the macro is finished, 
you can stack, as the last subcommand in the procedure, a TYPE 
subcommand, to display the current line. Or, if you write an edit macro 
that terminates when an end-of-file condition occurs the EOF: message 
issued by the editor may indicate the completion of the macro. 

I^.RU.1* IJPI; AC E : To change from edit mode to input mode in an edit macro, 
you can use the INPUT and REPLACE subcommands. In a fixed- length EXEC 
file, you must stack these subcommands using the &STACK control 
statement: 

6STACK INPUT 

— or — 

&STACK REPLACE 

If you use either of these subcommands following an &BEGSTACK control 
statement, the subcommand line is padded with blanks to the line length 
and the result is a line of blanks inserted into the file. 

In a variable-length EXEC file, lines are not padded with blanks, so 
the INPUT and REPLACE subcommands with no data line execute the same 
following an &BEGSTACK control statement as they do when stacked with 
the SSTACK control statement. 
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Going From Incut Mode to Jdit Mode: To stack a null line in an edit 
macro, to cause the editor to leave" input mode, you must use the SSTACK 
control statement with no other tokens, as follows: 

SSTACK 

CHANGE* DSTRIKG, LOCATE^ If Y " «ant to use the CHANGE, DSTRING, or 
LOCATE subcommands in an EXEC, you must take into account that when you 
stack any of these subcommands using the SSTACK control statement, all 
of the character strings on the line are truncated or padded to 8 
characters. Also, if you want to use a variable value for a character 
string, you are limited to 8 characters, all uppercase. 

For example, if a macro is used to locate a character string and 
delete the line on which it appears, the LOCATE subcommand has a 
variable symbol: 

SSTACK LOCATE /S1 
SSTACK DEL 

L1AGE, TABSET, OVERLAY: The TABSET and OVERLAY subcommands allow you to 
set margins and column stops for records in a file and to overlay 
character strings in particular positions. For example, the following 
macro places a vertical bar in columns 1, 15, 40, and 60 for all records 
in the file from the current line to the end of the file: 

SBEGSTACK 

PRESERVE 

IMAGE ON 

TABSET 1 15 40 60 

REPEAT * 

|->|->|->| 

RESTORE 

SEND 

In the above example, the «->•• symbol represents a tab character 
(X'05*). To create this EXEC, you can either issue the EDIT subcommand 

image off 

and use the Tab key (or eguivalent) on your terminal when you enter the 
line, or you can enter some other character and use the ALTER subcommand 
to alter that character to a X'OS 1 . 

If you want to overlay only one character string in a particular 
position in a file, you can use the TABSET subcommand to set that column 
position as the left margin, and then use the OVERLAY conmand, as 
follows: 

SCONTROL OFF 

SBEGSTACK 

PRESERVE 

VERIFY OFF 

TRONC * 

TABS 72 

SEND 

SSTACK REPEAT S1 

SBEGSTACK 

OVERLAY C 

RESTORE 

SEND 
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If you name this file $CONT EXEC, and if you invoke it with the line: 

$cont 3 

then the OVEHLAY subcommand is executed on three successive lines, to 
place the continuation character "C" in column 72. 

THE STACK SUBCOMMAND 

The STACK subcommand allows you to stack up to 25 lines from a file in 
the console stack. The lines are not deleted from the file, but the line 
pointer is moved to point to the last line stacked. 

You can also use the STACK subcommand to stack EDIT subcommands. You 

might do this if there were subcommands that you wanted to place in the 

stack to execute after all the subcommands stacked by the EXEC had 
executed. 

These techniques are used in the two edit macros that are distributed 
with the VM/370 system:, $MOVE and $DUP. If you want to examine these 
files for examples of how to use the STACK subcommand, you can display 
the files by entering, from the CMS environment: 

type $move exec * 

type $dup exec * 

An additional use of the STACK subcommand is shown in "An Annotated 
Edit Macro." 
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An Annotated Edit Macro 

The edit macro shown below, $DOUBLE, can be used to double space a CMS 
file. Regardless of where the current line pointer is, a blank line is 
inserted in the file following every existing line. The statements in 
the edit macro are separated into groups; the number to the left of a 
statement or group of statements indicates an explanatory note. The 
numbers are not part of the EXEC file. 



O 



O 
O 



© 



SCONTROL OFF 

SIF SINDEX = 1 SIF S1 = ? &GOTO -TELL 

&IF &INDEX = 1 &IF 61 = TWO 8G0T0 -LOOP 

SIF SINDEX NE &GOTO -TELL 

SIF SREADFLAG EC STACK &REAE VARS &GARB 

S STACK 

&STACK PRESERVE 

&STACK VERIFY OFF 

SSTACK BOTTOM 
&STACK I XXXXXXXX 
SSTACK TCP 



Motes : 

OThe &CONTROL statement suppresses the display of CMS commands, in 
this case, the DESBUF command. 
A The first &IF statement checks whether IDOUBLE has been invoked 
with a guestion mark (?) , in which case control is passed to the 
statement at the label -TELL. STYPE control statements at -TELL 

©explains what the macro does. 
The second SIF statement checks whether $DOUBLE has been invoked 
with the argument TWO, which indicates that the macro has executed 
itself, so the subcommands that initialize the file are stacked 

©only once. 
There are three ways to properly invoke this edit macro: with a ?, 
with the argument TWO, or with no arguments. The third SIF 
statement checks for the (no arguments) condition; if the macro is 
invoked any other way, control is passed to the label -TELL, which 
-^ explains the macro usage. 

(^ The SREADFLAG special variable is checked. If $DOUBLE is executed 
at the top or at the end of the file, the token TOF or EOF is in 

©the stack, and should be read out. 
A null line is placed in the console stack for loop control (see 
Hote 9.) The PRESERVE and VERIFY subcommands are stacked so that 
the editor does not display each line in the file as it executes 
— ^ the stacked subcommands. 

Qp The BOTTOM, INPUT, and TOP subcommands initialize the file by 
placing a marker at the bottom of the file, and then positioning 
the current line pointer at the top of the file. 
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© 

© 



© 



© 
© 
© 



© 



-LOOP 
&BEGSTACK 
NEXT 
STACK 1 

INPUT 
SEND 

&READ ABGS 

SIF .61 = . SSKIP 

SIF B1 EQ XXXXXXXX SSKIP 2 

-ENDLOOP &STACK $DOUBLE TWO 

SEXIT 

DESBUF 

&BEGSTACK 

UP 2 

DEL 3 

TYPE 

RESTORE 

SEND 

SEXIT 

-TELL 

SIF &READFLAG EQ STACK &READ VARS 

SBEGTYPE 

CORRECT FORM IS: $DOUBLE 

THIS EXEC DOUBLE SPACES A FILE BY INSERTING 
A BLANK LINE FOLLOWING EVERY LINE IN THE FILE 
EXCEPT THE LAST. 
SEND 



The NEXT, STACK, and INPUT subcommands are going to be repeated for 
each line in the file. The INPUT subcommand with no data line 
stacks a null line. Note that in order for $DOUBLE to execute this 
subcommand properly, $DOUBLE EXEC must have fixed-length records. 
Each line is stacked, with the STACK subcommand; this stacked line 
is checked in the read loop (Note 9) . When the stacked line is 
egual to the marker, XXXXXXXX, it indicates that the end of the 
file has been reached. 

These lines check for an end of file, which occurs when the line 
containing the marker is read. The first time this loop is 
executed, the stack contains the null line (statement 6), so the 
check for the marker is skipped. 

The last subcommand stacked is $DOUBLE TWO, which re-invokes 
SDOUBLE, but causes it to skip the first seguence of subcommands. 
The SEXIT statement causes an exit from SDOUBLE, so that all the 
EDIT subcommand stacked thus far are executed. 

When the marker is read in, the EXEC clears the stack, moves the 
current line pointer to pcint to the null line added above the 
marker, and deletes that line, the marker, and the null line that 
was inserted following the marker. The RESTORE subcommand restores 
editor settings. 

This edit macro is self-documenting. If $DOUBLE is invoked with a 
guestion mark, or invoked with an argument, information regarding 
its proper use is displayed. 
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User- Written Edit Macros 

You can create the edit macros shown below, for your own use in CMS. 
You may want to refer to them as examples when you are learning to write 
your own macros. The macros have not been formally tested by IBM; they 
are presented for your convenience only. 



$MACROS 

The $MACROS edit macro verifies the existence of and describes the usage 
of edit macros. If you enter 

$macros 

it lists the filenames of all the edit macros on your accessed disks. 
If you enter 

$macros namel name2 

it displays, for each valid macro name entered, the macro format and 
usage. (This macro assumes that all macros have been designed to 
respond to a ? request.) The format of the $MACROS edit macro is: 



| $MACROS | [filenamel [ f ilename2 [ f ilenamen ] ] ] I 



filename is the filename (s) of macro files whose usage is to be 
displayed. If filename is omitted, the filenames of all 
available macro files are listed. 

To create $HACROS, enter: 

edit $macros exec 

and in input mode, enter the following: 
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SCONTRCL OFF 

&IF SINDEX EQ 1 &IF &1 EQ ? SGOTO -TELL 

SIF SINDEX GT &GOTO -PARTIC 

* 

&BEGTYPE ALL 

EXEC FILES STARTING WITH A COLLAR-SIGN ARE AS FOLLOWS. 

FOR INFORMATION ON ONE OR MORE OF THEM, TYPE: 

$MACROS FILENAME1 <FILENAME2> 

SEND 

LISTF $* EXEC * (NOHEADER FNAME) 

&EXIT 

* 

-PARTIC STRIP = 

SINDEX 1 = 

* 

SLOOP -ENDLOOP SINDEX 
&INDEX1 = SINDEX1 + 1 
&SUB = SSUBSTR SSINDEX1 1 1 
SIF &SUB EQ $ &GOTO -STATIT 

STYPE SSINDEX1 IS INVALID 
STRIP = 1 
SGOTO -ENDLOOP 

-STATIT STATE &&INDEX1 EXEC * 
SIF SRETCODE EQ SGOTO -CALLIT 
STYPE &&INDEX1 NOT FOUND 
STRIP = 1 
SGOTO -ENDLOOP 
-CALLIT EXEC SSINDEX1 ? 
-ENDLOOP 

&EXIT STRIP 

* 

-TELL SBEGTYPE 

•$MACROS' HANDLES THE »$MACROS» REQUEST. 

TYPE «$MACROS» ALONE FOR MORE INFORMATION. 

SEND 

SEX IT 



$MARK 

The $MARK edit macro inserts from 1 to 6 characters, starting with the 
current line and in the column specified, for a specified number of 
records. If you enter 

$mark 

the macro places an asterisk (*) in column 72 of the current line. If 
you enter 

$mark 10 30 abc 

the macro places the string ABC beginning in column 30 in each of ten 
records, beginning with the current record. The format of the $MARK 
edit macro is: 



I I r r r in 

| $MARK | | n | col | char | I I 

I I I 1 I 22 I * I I I 

I I L J L JJJ 
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w her e : 

n indicates the number of consecutive lines, starting with the 
record currently being pointed to, that will be marked. If n is 
not specified, 1 is assumed, and the other default values are 
also assumed. 

col indicates the starting column in each record where the character 
string is to be inserted. The default is column 72. 

char indicates from 1 to 6 characters to be inserted in each record. 
The default is an asterisk (*) . 

To create $MARK, enter: 

edit $mark exec 

and in input mode, enter the following: 

SCONTROL OFF 

6IF SINDEX EQ 1 &IF &1 EQ ? SGOTO -TELL 

8IF SINDEX GT 3 SGOTO -BADPARM 

&INDEX1 = 1 

&IF SIHDEX GT &INDEX1 = &1 

&IF &INDEX1 LT SGOTO -BADPARM 

&INDEX2 =72 

&IF SINDEX GT 1 SINDEX2 = S2 

SIF SINDEX2 LT &GCTO -BADPARM 

&IF &INDEX2 GT 133 SGOTO -BADPARM 

SCHAR = * 

SIF &INDEX EQ 3 SCHAR = S3 

SLEN3 = SLENGTH SCHAR 

SIF &LEN3 GT 6 SGOTO -BADPARM 

SSTACK LIFO RESTORE 

&STACK LIFO OVERLAY (TAB) * SCHAR 

SSTACK LIFO REPEAT SINDEX1 

SSTACK LIFO TABS &INDEX2 

SBEGSTACK LIFO 

IMAGE ON 

TRONC * 

VERIFY OFF 

LONG 

PRESERVE 

SEND 

SEX IT 

* 

-BADPARM SBEGTYPE 

INVALID SHARK OPERANDS 

SEND 

SEX IT 1 

* 

-TELL SBEGTYPE 

CORRECT FORM IS: $MARK <N <COL <CHAR»> 

PUTS A 1-6 CHARACTER STRING IN COLUMN , COL« OF »N' LINES, STARTING 

WITH THE CURRENT LINE. THE NEW CURRENT LINE IS THE LAST LINE 

MARKED. DEFAULTS ARE: N= 1 ; COL=72; CHAR=*. 

SEND 

SEXIT 



*The word (TAB) represents pressing the Tab key (or equivalent logical 
tab) and should not be included in the data line. Instead, enter the 
appropriate tab character. 
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$POINT 

The $POINT edit macro positions the current line pointer at the 
specified line number. The line numbers must be in columns 73 through 80 
and padded with zeros. For example, if you enter 

$point 800 

the current line pointer is positioned at the line that has the serial 
number 00000800 in columns 73 through 80. The format of the $P0INT 
macro is: 

| $P0INT | key 

where: 

key is a 1 - to 8-character line number. If the specified key is less 
than 8 characters long, it is padded with leading zeros. 

To create $P0INT, enter: 

edit $point exec 

and in input mode, enter the following: 

SCONTROL OFF 

SIF SINDEX EQ &G0T0 -TELL 

&IF SINDEX EQ 1 &IF &1 EQ ? &GOTO -TELL 

SIF SINDEX GT 1 &G0T0 -BADPARM 

&KEYL = SLENGTH &1 

SINDEX1 = 8 - SKEYL 

&Z = &SUBSTR 00000000 1 &INDEX1 

S1 = SCONCAT SZ S1 

&STACK LIFO RESTORE 

SSTACK LIFO FIND (TAB)* &1 

&BEGSTACK LIFO 

TOP 

TABS 1 72 

IMAGE GN 

LONG 

PRESERVE 

SEND 

SEXIT 

♦ 

-BADPARM SBEGTYPE ALL 
INVALID $ POINT OPERANDS 
SEND 
SEXIT 1 

♦ 

-TELL SBEGTYPE ALL 

CORRECT FORM IS: $EOINT KEY 

IF *KEY* CONTAINS LESS THAN 8 CHARACTERS, IT IS PADDED WITH LEADING 

ZEROS. THE FILE IS THEN SEARCHED FROM THE TOP FOR •KEY 1 IN COLUMNS 

73-80. 

SEND 

SEXIT 



*The word (TAB) represents pressing the Tab key (or eguivalent logical tab) 
and should not be included in the data line. Instead, enter the appropriate 
tab character. 

Section 17. Writing Edit Macros 309 



$COL 

The $COL edit macro inserts, after the current record in the file, a 
line containing column numbers (that is, 1, 6, 11, ..., 76) . The format 
of the $COL macro is: 



I $COL | | 

No operands are used with $COL. 

If any arguments are entered, the macro usage is explained. 

To create $COL, enter: 

edit $col exec 
and in input mode, enter the following: 

SCONTROL OFF 

&IF &INDEX NE &GOTO -TELL 
SSTACK LIFO RESTORE 
SSTACK LIFO 
&BEGSTACK LIFO ALL 

1 6 11 16 21 26 31 36 41 46 51 56 61 66 71 76 
SEND 

SSTACK LIFO INPUT 
&BEGSTACK LIFO 
TRUNC * 
VERIFY OFF 
LONG 

PRESERVE 
SEND 
SEX IT 

-TELL 8BEGTYPE 

CORRECT FORM IS: $COL 

INSERTS A LINE INTO THE FILE SHOWING COLUMN NUMBERS. 

SEND 

SEXIT 
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Appendixes 



This publication contains the following appendixes: 

A. Summary of CHS Commands 

B. Summary of CP Commands 

C. Considerations for 3270 Display Terminal Users 

D. Sample Terminal Sessions 
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Appendix A: Summary of CMS Commands 



Figure 22 contains an alphabetical list of the CMS commands and the 
functions performed by each. Unless otherwise noted, CMS commands are 
described in VM/370: CMS Command §.nd Macro Reference. 



Code 
DOS PP 



EREP 



IPCS 



Meaning 

indicates that this command invokes a DOS Program Product, 

available from IBM for a license fee. 

indicates that this command is described in Vj1^370: 
IS2iE2SI5:£tal Recording, Editing, and Priniijag (UUP) 
Prog ram . 

indicates that this command is a part of the Interactive 
Problem Control System (IPCS) and is described in VM/370: IPCS 
User^ Guide. 



Op Gd indicates that this command is described in the VM/370: 
0£§JE§ior2.s Guide. 

OS PP indicates that this command invokes an OS Program Product, 
available from IBM for a license fee. 

SCRIPT indicates that this command invokes a text processor that is 
an IBM Installed User Program, available from IBM for a 
license fee. 

SPG indicates that this command is described in the VM/370: Sjstem 
Programmer's Guide. 

SYSGEN indicates that this command is described in the VM/370: 
£2. a J!£.ilL!9 and System Generation Guide. 



In addition to the commands listed in Figure 22, there are seven 
commands called Immediate commands which are handled in a different 
manner from the others. They may be entered while another command is 
executing by pressing the Attention key (or its eguivalent) and are 
executed immediately. The Immediate commands are: 

HB - Halt batch execution 

HO - Halt tracing 

HT - Halt typing 

HX - Halt execution 

RO - Resume tracing 

RT - Resume typing 

SO - Suspend tracing 



Appendix A: Summary of CMS Commands 313 



Command 
ACCESS 

AMSERV 

ASM3705 

ASSEMBLE 

ASSGN 

CMSBATCH 
COBOL 

COMPARE 

CONVERT 

COPYFILE 

CP 

CPEREP 

DDR 

DEBUG 
DIRECT 

DISK 

DLBL 

DOSGEN 
DOSLIB 

DOSLKED 

DOSPLI 
DSERV 



| Code | 



Usage 



Identify direct access space to a CMS virtual 
machine, create extensions and relate the disk 
space to a logical directory. 

Invoke Access Method Services utility functions to 
create, alter, list, copy, delete, import, or 
export VSAM catalogs and data sets. 

SYSGEN lAssemble 3704/3705 source code. 

Assemble Assembler Language source code. 

Assign or unassign a CMS/DOS system or programmer 
logical unit for a virtual I/O device. 

Invoke the CMS Batch Facility. 

OS PP | Compile OS ANS Version 4 or OS/VS COBOL source 
code. 

Compare records in CMS disk files. 

OS PP I Convert free form FORTRAN statements to fixed form. 

Copy CMS disk files according to specifications. 

Enter CP commands from the CMS environment. 

Edit and print error information which was recorded 
by VM/370 error recording routines. 

Perform backup, restore, and copy operations for 
disks. 

Enter DEBUG subcommand environment, debug mode. 

Set up VM/370 directory entries. 



EREP 



Op Gd, 
SYSGEN 



Op Gd, 
SYSGEN 



Perform disk— to— card and card— to- disk operations 
for CMS files. 

Define a DOS filename or VSAM ddname and relate 
that name to a disk file. 

SYSGEN |Load and save the CMSDOS shared segment. 

Delete, compact, or list information about the 
phases of a CMS/DOS phase library. 

Link-edit CMS text decks or object modules from a 
DOS/VS relocatable library and place them in 
executable form in a CMS/DOS phase library. 

DOS PP | Compile DOS PL/I source code under CMS/DOS. 

Display information contained in the DOS/VS core 
image, relocatable, source, procedure, and 
transient directories. 



Figure 22. CMS Command Summary (Part 1 of 4) 
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I 

Command 

DUMPSCAN 

EDIT 

ERASE 
ESERV 

EXEC 



FCOBOL 


DOS PP 


FETCH 




FILEDEF 




FORMAT 




FORTGI 


OS PP 


FORTHX 


OS PP 


GEN3705 


SYSGEN 


GENDIRT 




GENMOD 




GLOBAL 





GOFCRT 

INCLUDE 

LISTDS 

LISTFILE 
LISTIO 



LKED 
LOAD 
LOADMOD 



MACLIB 



Code 
IPCS 



OS PP 



SYSGEN 



Usage 

Provide interactive analysis of CP abend dumps. 

Invoke the CMS Editor to create or modify a disk 
file. 

Delete CMS disk files. 

Display, punch or print an edited (compressed) 
macro from a DOS/VS source statement library 
(E sublibrary) . 

Execute special procedures made up of frequently 
used sequences of commands. 

Compile DOS/VS COBOL source code under CMS/DOS. 

Fetch a CMS/DOS or DOS/VS executable phase. 

Define an OS ddname and relate that ddname to any 
device supported by CMS. 

Prepare disks in CMS 800— byte block format. 

Compile FORTRAN source code using the G1 compiler. 

Compile FORTRAN source code using the H— extended 
compiler. 

Generate an EXEC file that assembles and link-edits 
the 3704/3705 control program. 

Fill in auxiliary module directories. 

Generate non-relocatable CMS files (MODULE files) . 

Identify specific CMS libraries to be searched for 
macros, copy files, missing subroutines, or DOS 
executable phases. 

Compile FORTRAN source code and execute the program 
using the FORTRAN Code and Go compiler. 

Bring additional TEXT files into storage and 
establish linkages. 

List information about data sets and space 
allocation on OS, DOS, and VSAM disks. 

List information about CMS disk files. 

Display information concerning CMS/DOS system and 
programmer logical units. 



Link— edit the 3704/3705 control program. 
Bring TEXT files into storage for execution. 
Bring a single MODULE file into storage. 
Create or modify CMS macro libraries. 
Figure 22. CMS Command Summary (Part 2 of 4) 
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Command |Code | 



Usage 



MODMAP 
MOVEFILE 

NCPDUMP 

OPTION 

PLIC 

PLICR 

PLIOPT 

PRB 
PRINT 
PROB 
PSERV 

PUNCH 
QUERY 
READCARD 
RELEASE 

RENAME 
RSERV 

RUN 

SAVENCP 
SCRIPT 
SET 



Op Gd, 
SYSGEN, 
SPG 



OS PP 



OS PP 



OS PP 



IPCS 



IPCS 



SYSGEN, 
SPG 

SCRIPT 



Display the load map of a MODULE file. 

Move data from one device to another device of the 
same or a different type. 

Process CP spool reader files created by 3704/3705 
dumping operations. 



Change the DOS COBOL compiler (FCOBOL) options that 
are in effect for the current terminal session. 

Compile and execute PL/I source code using the 
PL/I Checkout Compiler. 

Execute the PL/I object code generated by the OS 
PL/I Checkout Compiler. 

Compile PL/I source code using the OS PL/I 
Optimizing Compiler. 

Update IPCS problem status. 

Spool a specified CMS file to the virtual printer. 

Enter a problem report in IPCS. 

Copy a procedure from the DOS/VS procedure library 
onto a CMS disk, display the procedure at the 
terminal, or spool the procedure to the virtual 
punch or printer. 

Spool a copy of a CMS file to the virtual punch. 

Reguest information about a CMS virtual machine. 

Read data from spooled card input device. 

Make a disk and its directory inaccessible to a CMS 
virtual machine. 

Change the name of a CMS file or files. 

Copy a DOS/VS relocatable module onto a CMS disk, 
display it at the terminal, or spool a copy to 
the virtual punch or printer. 

Initiate series of functions to be performed on a 
source, MODULE, TEXT, or EXEC file. 

Read 3704/3705 control program load into virtual 
storage and save an image on a CP— owned disk. 

Format and print documents according to embedded 
SCRIPT control words in the document file. 

Establish, set, or reset CMS virtual machine 
characteristics. 



Figure 22. CMS Command Summary (Part 3 of 4) 
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Command 
SETKEY 

SORT 

SSERV 

START 

STAT 

STATE 

STATEW 

SVCTRACE 

SYNONYM 

TAPE 

TAPEMAC 

TAPPDS 

TESTCOB 
TESTFORT 
TXT LIB 
TYPE 
UPDATE 

VMFDUMP 

VMFLOAD 

VSAMGEN 

VSAPL 

VSBASIC 

VSBDTIL 

ZAP 



ICode 
SPG 



IPCS 



OS PP 
OS PP 



Op Gd 
IPCS 

SYSGEN 

SYSGEN 

OS PP 

OS PP 

OS PP 

Op Gd, 

SYSGEN, 

SPG 



Usage 

Assign storage protect keys to storage assigned to 
named systems. 

Arrange a specified file in ascending order 
according to sort fields in the data records. 

Copy a DOS/VS source statement book onto a CMS 
disk, display it at the terminal, or spool a copy 
to the virtual punch or printer. 

Begin execution of programs previously loaded (OS 
and CMS) or fetched (CMS/DOS). 

Display the status of reported system problems. 

Verify the existence of a CMS disk file. 

Verify a file on a read/write CMS disk. 

Record information about supervisor calls. 

Invoke a table containing synonyms you have created 
for CMS and user-written commands. 

Perform tape-to-disk and disk-to-tape operations 
for CMS files, and position tapes. 

Create CMS MACLIB libraries directly from an 
IEHMOVE-created partitioned data set on tape. 

Load OS partitioned data set (PDS) files or card 
image files from tape to disk. 

Invoke the OS COBOL Interactive Debug Program. 

Invoke the FORTRAN Interactive Debug Program. 

Generate and modify text libraries. 

Display all or part of a CMS file at the terminal. 

Make changes in a program source file as defined 
by control cards in a control file. 

Format and print system abend dumps; under IPCS, 
create a problem report. 

Generate a new CP, CMS or RSCS module. 

Load and save the VSAM shared segment. 

Invoke the VS APL interface. 

Compile and execute VS BASIC programs under CMS. 

Convert BASIC 1.2 data files to VS BASIC format. 

Modify or dump LOADLIB, TXTLIB, or MODULE files. 



Figure 22. CMS Command Summary (Part 4 of 4) 
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Appendix B: Summary of CP Commands 



Figure 23 describes the CP command privilege classes. 



Class 
A* 



C*,2 
D* 

E*, 2 
F*, 3 



Any 



H 



1 .4 



User and Function 



l^iiary System Operator: The class A user controls the 
VM/370 system. Class A is assigned to the user at the VM/370 
system console during IPL. The primary system operator is 
responsible for the availability of the VM/370 system and its 
communication lines and resources. In addition, the class A 
user controls system accounting, broadcast messages, virtual 
machine performance options and other command operands that 
affect the overall performance of VM/370. 

Note: The class A system operator who is automatically legged 
on during CP initialization is designated as the primary 
system operator. 

System Resource Operator: The class B user controls all the 
real resources of the VM/370 system, except those controlled 
by the primary system operator and spooling operator. 

System Programmer: The class C user updates certain 
functions of the VM/370 system. 

Spooling Operator: The class D user controls spool data 
files and specific functions of the system's unit record 
eguipment. 

System Analyst: The class E user examines and saves certain 
data in the VM/370 storage area. 

Service Repr es en t at iye : The class F user obtains, and 
examines, in detail, Certain data about input and output 
devices connected to the VM/370 system. 

General User: The class G user controls functions associated 
with the execution of his virtual machine. 

The Any classification is given to certain CP commands that 
are available to any user. These are primarily for the 
purpose of gaining and relinquishing access to the VM/370 
system. 

Reserved for IBM use. 



*D escribed in the VM/370: Opera tor Is Guide. 

2 Described in the VM/370: System Programmer's Guide and the 
Y.HZJ70J System Logic and Problem Determination Guide. 
3 Described in the VM/370: QLTSEP and Error Recording Guide. 
♦Described in the VM/370 : CP command Reference for General Users 

Figure 23. CP Privilege Class Descriptions 
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Figure 24 contains an alphabetical list of the CP commands, the 
privilege classes which may execute the command, and a brief statement 
about the use of each command. 



Command 

#CP 
ACNT 
ADSTOP 
ATTACH 

ATTN 
ADTOLOG 
BACKSPAC 
BEGIN 

CHANGE 

CLOSE 

COUPLE 
CP 

DCP 

DEFINE 
Figure 24. 



Privilege 
Class 

any 

any 

A 



A,B 



D,G 



G 
any 

C,E 
G 
CP Command 



Usage 



Annotate the console sheet. 

Execute a CP command while remaining in the 
virtual machine environment. 

Create accounting records for logged on users 
and reset accounting data. 

Halt execution at a specific virtual machine 
instruction address. 

Attach a real device to a virtual machine. 
Attach a EASD device for CP control. 
Dedicate all devices on a particular channel 
to a virtual machine. 

Make an attention interruption pending for the 
virtual machine console. 

Automatically log on a virtual machine and 
have it operate in disconnect mode. 

Restart or reposition the output of a unit 
record spooling device. 

Continue or resume execution of the virtual 
machine at either a specific storage location 
or at the address in the current PSH. 

Alter one or more attributes of a closed spool 
file. 

Terminate spooling operations on a virtual card 
reader, punch, printer, or console. 

Connect channel— to-channel adapters. 

Execute a CP command while remaining in the CMS 
virtual machine environment. 

Display real storage at terminal. 

Reconfigure your virtual machine. 

Summary (Part 1 of 4) 
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Command 
DETACH 



DIAL 



DISABLE 


A,B 


DISCONN 


any 


DISPLAY 


G 


DMCP 


C,E 



DRAIN 
DUMP 

ECHO 

ENABLE 
EXTERNAL 

FLUSH 

FORCE 

FREE 

HALT 

HOLD 

INDICATE 
IPL 
LINK 

LOADBOF 



Privilege 
Class 

B 
B 
B 
G 
G 

any 



A,B 
G 



A 
D 
A 

D 

E,G 
G 
G 



Usage 

Disconnect a real device from a virtual machine. 

Detach a DASD device from CP. 

Detach a channel from a specific user. 

Detach a virtual device from a virtual machine. 

Detach a channel from your virtual machine. 

Connect a terminal or display device to the 
virtual machined virtual communication line. 

Disable 2701/2702/2703 , 3704/3705 in EP mode, 
and 3270 local communication lines. 

Disconnect your terminal from your virtual 
machine. 

Display virtual storage on your terminal. 

Dump the specified real storage location on your 
virtual printer. 

Halt operations of specified spool devices upon 
completion of current operation. 

Print the following on the virtual printer: 

virtual PSW, general registers, floating-point 
registers, storage keys, and contents of 
specified virtual storage locations. 

Test terminal hardware ty redisplaying data 
entered at the terminal. 

Enable communication lines. 

Simulate an external interruption for a virtual 
machine and return control to that machine. 

Cancel the current file being printed or punched 
on a specific real unit record device. 

Cause logoff of a specific user. 

Remove spool HOLD status. 

Terminate the active channel program on 
specified real device. 

Defer real spooled output of a particular user. 

Indicate resource utilization and contention. 

Simulate IPL for a virtual machine. 

Provide access to a specific DASD device by a 
virtual machine. 

Load real UCS/UCSB or FCB printer buffers. 



Figure 24. CP Command Summary (Part 2 of 4) 
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Privilege 


Command 


| Class 


LOADVFCB 


1 G 


LOCATE 


C r E 


LOCK 


A 


LOGOFF 


any 


LOGON 


any 


MESSAGE 


A, B,any 


MONITOR 


A,E 


NETWORK 


A,B r F 



NOTREADY 

ORDER 

PURGE 
QUERY 

READY 

REPEAT 

REQUEST 

RESET 

REWIND 
SAVESYS 

SET 



Figure 24 . 



D,G 



D,G 



A,B,C,D, 
E,F,G 



A,B,F, G 



Usage 

Load virtual forms control buffer for a virtual 
3211 printer. 

Find CP control blocks. 

Bring virtual pages into real storage and lock 
them; thus excluding them from future paging. 

Disable access to CP. 

Provide access to CP. 

Transmit messages to other users. 

Trace events of the real machine and record 
system performance data. 

Load, dump r trace and control the operation of 
the 3704/3705 control program. Control the 
operation of 3270 remote devices. 

Simulate "not ready" for a device to a virtual 
machine. 

Rearrange closed spool files in a specific 
order. 

Remove closed spool file from system. 

Reguest information about machine configuration 
and system status. 

Simulate device end interruption for a virtual 
device. 

Repeat (a specified number of times) printing or 
punching of a specific real spool output file. 

Make an attention interruption pending for the 
virtual machine console. 

Clear and reset all pending interruptions for a 
specified virtual device and reset all error 
conditions. 

Rewind (to load point) a tape and ready a tape 
unit. 

Save virtual machine storage contents, 
registers, and PSH. 

Operator — establish system parameters. | 

User — control various functions within the 
virtual machine. 



CP Command Summary (Part 3 of 4) 
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Command 


Privilege 
Class 


Usage 


SHUTDOWN 


A 




Terminate all VM/370 functions and checkpoint CP 
system for warm start. 


SLEEP 


an 


y 


Place virtual machine in dormant state. 


SPICE 


1 D 




Force single spacing on printer. 


SPOOL 


G 




Alter spooling control options; direct a file to 
another virtual machine or to a remote 
location via the RSCS virtual machine. 


START 


D 




Start spooling device after draining or changing 
output classes. 


STCP 


C 




Change the contents of real storage. 


STORE 


G 




Alter specified virtual storage locations and 
registers . 


SYSTEM 


G 




Simulate RESET, CLEAR STORAGE and RESTART 
buttons on a real system console. 


TAG 


G 




Specify variable information to be associated 
with a spool file or output unit record 
device. 

Interrogate the current TAG text setting of a 
given spool file or output unit record device. 


TERMINAL 


G 




Define or redefine the input and attention 
handling characteristics of your virtual 
console. 


TRACE 


G 




Trace specified virtual machine activity at your 
terminal, spooled printer, or both. 


TRANSFER 


D, 


G 


Transfer input files to or reclaim input files 
from a specified user's virtual card reader. 


UNLOCK 


A 




Unlock previously locked page frames. 


VARY 


B 




Mark a device unavailable or available. 


WARNING 


A, 


B 


Transmit a high priority message to a specified 
user or to all users. 



I 

Figure 24. 



CP Command Summary (Part 4 of 4) 
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Appendix C: Considerations for 3270 Display Terminal Users 



The IBM 3270 Display terminal, commonly referred to as a 3270, functions 
somewhat differently from a typewriter-style terminal when you use it as 
a virtual machine console under VM/370. Apart from the obvious 
difference in the way output is displayed, there are special techniques 
you can use with a 3270 that you cannot use on a 2741 or other 
typewriter terminal. This appendix describes how to use a 3270, and 
provides additional notes to supplement discussions in the first part of 
this publication. 



Entering Commands 

Since the keyboard on a 3270 is never locked during the execution of a 
command or program, you can enter successive command lines without 
waiting for the completion of the previous command. This stacking 
function can be combined with the other methods of stacking lines, such 
as using the logical line end symbol (#) to stack several command 
lines. If you try to enter more lines than the terminal buffer can 
accommodate, however, you receive the status message NOT ACCEPTED and 
you must wait until the buffer is cleared before you can enter the 
line. 

You will find, as you become accustomed to using a 3270, that the #CP 
function is very useful. The #CP function, remember, is a function that 
allows you to pass a command line to the control program immediately, 
bypassing any processing by the virtual machine (CHS). The #CP function 
can be used in any VM/370 environment, and you can enter it even when a 
program is executing. You do not have to interrupt a program's execution 
to enter a command line such as 

#cp display psw 
to display the current PSH, or 

#cp spool printer class s 
to spool your virtual printer. 



Setting Program Function Keys 

If there are CP and CMS commands that you use frequently, you can set 
the program function (PF) keys on your terminal to execute them. Some 
examples of commands you might wish to catalog on PF keys are 

#CP DISPLAY PSW 

#CP QUERY PRINTER ALL 

QUERY SEARCH 

To set functions keys 1,2, and 3 to perform these command functions, 
enter: 

cp set pfl immed n #cp display psw 

cp set pf2 immed "#cp query printer all 

cp set pf3 immed query search 
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When you want to execute a #CP function with a PF key, or you want a PF 
key to execute a series of commands, you must use the logical escape 
symbol (••) when you enter the SET command. 

cp set pf5 immed edit test file"#bo M #input line"#file 
sets the PF5 key as 

EDIT TEST FILE#BO#INPUT LINE#FILE 

You cannot set lowercase characters in a PF key. 

The above examples use the IMMED operand of the SET command, which 
specifies that the function is performed as soon as you press the PF 
key. You can also set a key so that it is delayed, that is, that the 
command or data line is placed in the user input area. Then, you must 
press the Enter key to execute the command; you may modify the line 
before you enter it. This is the default setting (DELAY) for program 
function keys. For example, you might set a key as 

QUERY DISK Xft 

When you press this PF key, the command line is placed in the user input 
etrea, with the cursor positioned following the "8" logical character 
delete symbol; you can enter the mode letter of the disk you are 
querying before you press the Enter key to execute the command. 

You can set all of your program function keys in your PROFILE EXEC, 
so they are set each time you load CMS. You can change a PF key setting 
any time during a terminal session, according to your needs. If, for 
example, you discover that you are repeating several procedures a number 
of times, and the procedure does not lend itself to being written into 
an EXEC, you could use your program function keys. 

All the lines in an EXEC procedure are scanned, and all character 
strings are truncated to 8 characters, so if you enter a long command 
line, insert spaces where possible: 

CP SET PF5 IMMED EDIT TEST FILE #B0# INPUT 

To change PF settings within the edit environment, give the EXEC a 
filename that begins with a dollar sign ($) , so it functions as an edit 
macro. 



Controlling the Display Screen 

A major feature of a 3270 display screen is the screen status area, 
which indicates, at all times that you are logged on, the current 
operating condition your virtual machine is in. Understanding the 
status conditions can help you use CMS on a 3270 more effectively. The 
screen status area indicates one of six conditions: 

CP READ: After you leg on, this is the first status message you see; it 
indicates that the terminal is waiting for a line to be read by the 
control program. You can enter only CP commands when the screen status 
area indicates a CP READ. 

y.M READ: This status indicates that your terminal is waiting for a line 
to be issued to your virtual machine; you may be in the CMS environment, 
in the edit or debug environments, or you may be executing a program or 
an EXEC that has issued a read to the console. 
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RUNNING: This status means that your virtual machine is operating. Once 
you have loaded CMS and are using the CMS environment, this status is 
almost continually in effect, even when you are not currently executing 
a command or program. 

You can alter the way this works by using the AUTOREAD function of 
the SET command. When the AUTOREAD setting is OFF, (the default for 
display terminals) , your terminal displays a RUNNING status after the 
execution of each CMS command. If you want the terminal to be in a VM 
READ status following each command, issue 

set autoread on 

The CN setting is the default for typewriter terminals, since a read on 
a typewriter terminal must be accompanied by the unlocking of the 
keyboard. 

The advantage of keeping your virtual machine in a running status 
even when it is not actually executing a program is that it makes your 
terminal ready to receive messages. If your terminal is waiting for a 
read, either from CF or from the virtual machine, and if a user or a 
program sends a message to your virtual console, then the message is not 
displayed until you use the Enter key to enter a command or null line. 
When your machine is in a running status, the terminal console is always 
ready to accept messages. 

If your virtual machine is in the CP environment, and you want your 
terminal to be in a running status, you can use the command: 

cp sleep 

To return to the CP BEAD status, you must press the PA1 key or the Enter 
key. 

MORE...: This status indicates that your display screen is full, but 
that there is more data to be displayed. This message, in addition to 
indicating that there is more data, gives you a chance to freeze your 
screen's current display so you can continue to examine it, if 
necessary. 

When you see the screen is in a MORE... status, you can either (1) 
press the Clear, Cancel, or PA2 keys to clear the screen and see the 
next screen, or (2) press the Enter key to hold the screen in its 
present status. If you do not do either, then after 60 seconds, the 
screen is cleared and the next screen is displayed. 

HOLDING: This indicates that you have pressed the Enter key to freeze 
the screen. You must use the Cancel, Clear, or PA2 keys to erase this 
screen and go on to the next display. 

A holding status also results if you have received a message that 
appeared on this screen. When the screen becomes full, it does not 
automatically pass to the next display after 60 seconds, but waits until 
you specifically clear the screen. (This feature ensures that any 
important messages you receive are not lost.) 

M9.T ACCEPTED: Indicates that you are trying to enter a command line but 
the terminal buffer is full and cannot accept it. 
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CONSOLE OUTPUT 

When you use a 3270 terminal as your virtual machine console, you do not 
ordinarily retain a console log, as you do on typewriter terminal. 
There may be many circumstances in which you need a printed record of 
your console output, whether it be to obtain a copy of program-generated 
output, or to retain a record of CP and/or CMS commands that resulted in 
an error condition. There are two techniques you can use in VM/370 to 
obtain hardcopy representations of display terminal sessions: spooling 
console output and the 3270 copy function. 

5£2224n<I Console Oujtput 

The CP SPOOL command provides the CONSOLE operand, which allows you to 
begin and end console spooling. You enter 

cp spool console start 

when you want to begin recording your terminal session, and 

cp spool console stop 

when you have finished. In between, you can periodically close the 
console file to release for printing whatever has been spooled thus far: 

cp spool console close 

Other operands that you can enter are the same as you might specify for 
any printer file, such as CLASS, COPY, CONT, and HOLD. 

An alternate technique is to spool your console to your own virtual 
reader: 

cp spool console start * class a 

Then, when you close the console file, instead of being released to the 
CP printer spool file queue, it is routed to your virtual card reader, 
and you can load it onto your A-disk as a CMS disk file: 

readcard console file 

You can then use the editor to examine it (or to delete sections you 
don't need) and use the PRINT command to spool it to the printer. 

3270 COPY Function 

If you are using a 3270 display terminal, and you have available a 3284, 
3286, or 3288 printer, you can copy the full screen display currently 
appearing on the screen. To copy the screen, you have to assign the 
copying function to a program function key, with the SET command: 

cp set pf9 copy 

Then, whenever you want to copy a screen display, you can press the PF9 
key (or whichever key you set) . The display is printed on any 3284, 
3286, or 3288 printer that is attached to the same control unit as the 
display terminal. If, when you press the PF key, the screen status area 
indicates NOT ACCEPTED, it means that the printer is either not ready or 
not available. When you press the PF key and receive no response, it 
means that the screen has been copied. 
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Figure 25 is an example of a 3270 screen display that could be copied 
on the printer. When you use the copy function to copy a screen, all 24 
lines of the display screen are copied; the screen status area 
(indicated as RUNNING in Figure 25) is blank. You can use the user 
input area of your screen to key in comments, or you name or userid, if 
several users are spooling copy files 



DEFINE STORAGE 16384K 

STORAGE = 16384K 

IPL 190 

CMS VERSION 3.0 02/28/76 



10:32 



RUNNING 



testl ...t. jones 



Figure 25. 3270 Screen Display 



Signaling Interrupts 

The two keys on your 3270 keyboard that signal interrupts are the PA1 
key and the Enter key. Throughout this publication, interrupt signaling 
has been described in terms of the Attention key, which is the interrupt 
signaling key on a 2741. 

On a typewriter terminal, the Attention key, pressed once, causes a 
virtual machine interrupt (if the terminal mode is set to VM) ; you must 
use it when you want to enter an Immediate command, such as HT or HX. 
On a display terminal, you can enter these commands whenever your 
virtual machine is in a running status, without having to signal an 
interrupt before you enter the command. 

Sometimes, however, if your terminal is displaying output very 
rapidly, you must wait until the screen is full and the screen status 
area indicates a MORE... status before you attempt to enter the HT or HX 
command. 

The Enter key can also be used as an interrupt signaling key. If you 
press it once when your virtual machine is running, you will place your 
virtual machine in the VM READ status, so you can enter a command line. 
If you press the Enter key twice, quickly, you enter the CP environment, 
with your console in a CP READ status. 

An easier way to enter the CP environment is by pressing the PA 1 key. 
Whenever you press this key, your virtual machine is placed in a CP READ 
status, and you can enter any CP command. From the CP environment, you 
must use the CP command BEGIN to resume execution of your virtual 
machine. 
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HALTING SCREEN DISPLAYS 

When your terminal is displaying successive screens of output from a 
program or a CMS command, you can use the HT or HX Immediate commands to 
halt the display or the execution of the command, respectively. If your 
terminal is writing the information at a very rapid rate, you may have 
difficulty entering the HT or HX command. In these circumstances, you 
can use the PA1 key (or press the Enter key twice) to force your 
terminal to a CP READ status. Then, you can use the CP command ATTN or 
REQUEST to to signal a virtual machine read. When the screen status area 
indicates VM READ, you can enter HX or HT. 



Using the CMS Editor with a 3270 

The CMS Editor has a special format and operation, called display mode, 
that makes editing CMS disk files with a 3270 more convenient than on a 
typewriter terminal. It uses most of the display screen, and displays 
up to 20 lines of a file at once. In addition to displaying data lines 
of the file, the editor also indicates, on the topmost line of the 
screen, the filename, filetype, record format, and logical record length 
of the file being edited, as well as showing your current mode: input or 
edit. The format of the screen is shown in Figure 26. 

The screen lines that you are most concerned with, while editing, are 
the current line (on the same line as the system available indicator) , 
the user input area (the bottom two lines) , and the editor's message 
line, the second line from the top, in which the editor's responses and 
error messages are displayed. 

When you first invoke the editor to edit a file, whatever is 
currently on the screen (including your EDIT command line) is erased and 
the full screen is controlled by the editor. The current line pointer 
is positioned at the top of the file, the top part of the display screen 
appears blank. The editor displays the characters "TOF:" and "EOF:" to 
indicate the top and end of the file, respectively. 



ENTERING EDIT SUBCOMMANDS 

when you enter an EDIT subcommand into the user input area and press the 
Enter key the subcommand is not displayed on the screen, but the change 
(or line pointer movement) is reflected in the screen display. If you 
enter a subcommand that moves the current line pointer, all of the lines 
on the screen are shifted up or down, according to the action taken by 
the subcommand. 

If you use the INPUT subcommand to enter input lines, the edit status 
field indicates INPUT; all of the lines that you enter are placed in the 
file and appear on the screen as the current line. (Entering input 
lines from a remote 3270 is somewhat different. "Editing on a Remote 
3270" below, discusses the differences.) 

If you enter an invalid EDIT subcommand, or if you enter a subcommand 
that reguests information, the edit response appears in the message 
field of the screen. For example, if you enter 

trunc 
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I — 

EDIT 1 DISPLAY SCREEN A1 2 F 80 3 
>»» 1 80 * 



TOF: 5 

THIS IS THE FIRST LINE OF THE FILE. (CURRENT LINE) 

THIS IS THE SECOND LINE OF THE FILE. 

THIS IS THE THIRD LINE OF THE FILE. 

EOF: 



VM READ 

N o te s : 

i Edit session status. This indicates EDIT, INPUT, or NEW FILE. 
The NEW FILE message appears when you edit a new file; it is 
replaced with INPUT when you enter input mode and thereafter is 
EDIT or INPUT. 

2 The filename, filetype, and filemode of the file. 

3 Record format and logical record length. 

♦ Editor reponse area. The response shown may be the response to 
a VERIFY subcommand entered with no operands. 

5 The symbols TOF: and EOF: indicate top- and end-of-file, 
respectively. 

6 The current line is always shown at line 9, opposite 
the system available indicator. 

Figure 26. How the CMS Editor Formats a 3270 Screen 



the editor responds by displaying the current truncation setting, which 
might be: 

>»» 81 

If you enter 

copyfile myfile edit (trunc 
the editor would respond: 

»»> ?EDIT: copyfile myfile edit (trunc 

to indicate that it does not recognize the entered line (COPYFILE is not 
an EDIT subcommand). When you use line-number editing, the prompting 
message appears in this area; after you enter text in the user, input 
area, the text line is written in the output display area, at the 
current line position. 
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Two EDIT subcommands, CHANGE and ?, result in lines being copied in 
the user input area. In the case of the CHANGE subcommand, the line that 
is displayed is the current line. Once in the user input area, you can 
modify it and re-enter it. While you are changing it, the original line 
appears unchanged in the output display area. If you decide that you do 
not want changes entered, you must press the Erase Input key and then 
press the Enter key before you enter any other EDIT subcommands. 

You can use the ? subcommand to request that the last EDIT subcommand 
you entered be displayed in the user input area. If, for example, you 
enter a CHANGE or LOCATE subcommand that results in a NOT FOUND 
condition, or some other error, you can enter 



and modify the subcommand line and re-enter it, if you want; otherwise, 
use the Erase Input key to delete it. 



CONTROLLING THE DISPLAY SCREEN 

Usually the editor controls the entire screen display during an edit 
session. Occasionally, the screen goes into a MORE... status, and you 
■ust use the Cancel key to clear the screen. There are two other 
situations in which the screen must be cleared, either by the editor, or 
by you. When you use the CMS subcommand to enter CMS subset to enter 
CMS commands, the screen is cleared and the message CMS SUBSET is 
displayed at the top of the screen. When you issue the subcommand RETURN 
to return to edit mode, the screen display is restored to its original 
appearance. 

The situation is slightly different, however, whenever you 
communicate with the control program (CP) , or receive messages from 
other users during an edit session. Any CP message or command response 
causes your screen to go into a MORE... status; you must use the PA2 
(Cancel) key to see the response. To restore your screen to its edit 
display, you should use the EDIT subcommand TYPE. If you use the PA1 
key to place your virtual machine in the CP environment, and the screen 
status area indicates CP READ, use the CP command BEGIN to restore edit 
mode. Then enter the TYPE subcommand. If you enter a subcommand other 
than TYPE, the entire screen is not restored, and the top two lines (the 
editor*s data and response fields) may contain lines of the CP 
response. 

If your virtual machine was in input mode when you entered the CP 
command, you may continue entering lines of input; the third through the 
ninth lines of the screen are restored after you enter the next line. 

If you enter a CP command that does not produce a response, then 
there is no change to the screen. 

Verification Settings on a 3270 

The VERIFY subcommand allows you to alter the verification columns when 
you are editing a file, or to cancel verification altogether. If, for 
example, you are editing a file with records longer than 80 characters, 
each line is displayed on two lines of the display screen. Sometimes, 
you may be editing only specific columns in a file, and do not need to 
see the lines displayed in their entirety. To see only the first 80 
columns, you could enter: 
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verify 1 80 

Or, if you wanted to see the last 80 columns of a file with 
120-character records, you could enter 

verify 41 120 

If you cancel verification entirely by entering 

verify off 

then, modifications that you make to the file (including movement of the 
current line pointer) are not reflected on the display screen until you 
use the TYPE subcommand. 



THE CURRENT LINE POINTER 

There is one aspect of the CMS Editor on a 3270 that is much the same as 
on a typewriter terminal: you must still be concerned with the 
positioning of the current line pointer, and you can only add or modify 
data on the current line, even though you see many lines being 
displayed. The current line, on the screen, appears near the middle, on 
the same line as the SYSTEM AVAILABLE light. 

To move the current line pointer, you can use the subcommands UP and 
DOWN: UP indicates movement toward the top of the file and DOWN 
indicates movement toward the bottom of the file. When you issue either 
of these subcommands, the entire display of the file shifts down the 
screen (if you use the UP subcommand) or up the screen (if you use the 
DOWN subcommand) . 

If you have never used the CMS Editor on a typewriter terminal, you 
may find the UP and DOWN subcommands confusing to use, so you can use 
instead the BACKWARD (UE) and FORWARD or NEXT (DOWN) subcommands to 
shift the display backward (toward the top of the file) and forward 
(toward the bottom of the file) . 

You can also use the EDIT subcommand SCROLL, which allows you to 
display successive screen displays, and to examine an entire file 
quickly. If you enter the SCROLL subcommand with no operands, it is the 
equivalent of entering the subcommand DOWN (FORWARD) 20, which results 
in the screen changing to display the 20 lines following the lines 
currently being displayed. If you enter 

scroll 10 

Then, the SCROLL subcommand executes 10 times, placing the screen in a 
MORE... state at the end of each display. 

If the file you are editing has verification column settings greater 
than 80 characters (so each line takes up 2 display lines) , then the 
SCROLL subcommand moves the screen 10 lines at once instead of 20. 

The UP (or BACKWARD) counterpart of SCROLL is SCBOLLUP, which can be 
abbreviated SU. 
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USING PROGRAM FUNCTION KEYS 

You can enhance the use of the CMS Editor on a 3270 by setting the 
program function (PF) keys on your terminal to correspond to some cf the 
more frequently-used EDIT subcommands, such as UE, DOWN, SCROLL, FILE, 
SAVE, and so on. You can also set a program function key to contain a 
line of data, so that if you are creating a file that has many duplicate 
lines in it, you can use the PI key instead of having tc key in the 
entire line each time. PF keys, cannot, however, contain lowercase 
character strings. 

You can set a program function key while you are in edit mode either 
by using the PA1 key to enter the CP environment or by using the #CP 
function. 



USING THE EDITOR IN LINE MODE 

The editor's display mode is the most common format of operation on a 
3270. There are, however, instances when it is not possible or not 
desirable to use the editor in display mode. For these instances, you 
should use the line mode of operation, which is the eguivalent to using 
a typewriter terminal. When you use line mode, each EDIT subcommand you 
enter, and the response (if you have verification on), is displayed, a 
line at a time, on the screen in the output display area. There is no 
full screen display of the file. 

You need only be concerned with using line mode if you are connected 
to VM/370 by a remote 3270 line, or if you are editing a file from 
within an EXEC and you want to control the screen display. Although it 
is possible to use the editor in line mode on a local 3270, it is rarely 
necessary for normal editing purposes. 

Editing 2R il l§12t§ J270 

When you invoke the editor from a remote 3270, you are placed in line 
mode by the editor. The advantage of using the 3270 in line mode 
(particularly on a remote terminal) is that the terminal can respond 
more quickly to display requests. When you use display mode, the 
terminal has to write out the entire output display area when you move 
the current line pointer; in line mode, it has only to write a single 
line. 

If you want to use display mode, you enter the EDIT subcommand 

format display 

And the editor begins operating in display mode, and you can use the 
special editing functions available in display mode. 

However, when you are using a remote 3270 in display mode, and you 
enter the INPUT subcommand to begin entering input lines, the screen is 
cleared, and your input lines are displayed as if you were in line mode, 
beginning at the top of the screen. When you enter a null line to return 
to edit mode, the editor returns to a full screen display. 

You can resume editing in line mode by using the subcommand: 

format line 
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Editing From an EXEC File 

If you invoke the editor from an EXEC, but you do not want the screen 
cleared when the editor gets control, you can specify the NODISP option 
on the EDIT command line : 

edit test file (nodisp 

This places the 3270 in line mode, so that the lines already on the 
screen are not erased. 

The 3270 remains in line mode for the remainder of the edit session, 
and you cannot use the FORMAT subcommand to place it in display mode. 

OSING SPECIAL CHARACTERS ON A 3270 

There are two special characters available on a typewriter terminal 
whose functions have no meaning on a display terminal. They are the tab 
character (X^S 1 ) and the backspace character (XM6 1 )* For most file 
creation and editing purposes, you will probably not need to use the 
backspace, but many CMS filetypes use tab settings to set up the proper 
column alignment in files. There are two methods you can use to enter 
any special character on a 3270 (including tabs) , and an additional 
method of using tabs, which involves setting a program function key. 

To enter any special character (a backspace is used in this example) 
you can either: 

1. Enter another character at the appropriate place in the record, and 
then use the ALTER subcommand to alter that character to the 
hexadecimal value of the character you want to represent (a 
backspace character is a X'16'). For example: 

input ABC>» 

alter > 16 1 *~" 

When you enter backspaces and overstrike characters on a 3270, 
however, the characters and backspaces each occupy character 
positions, so that a single compound character occupies three 
character positions on the screen. If the image setting is CANON, 
and you want to use the backspace to enter compound characters, you 
must not enter the backspace character first. 

2. Before you begin to create the file, use the CMS SET command to 
define some other character as the backspace character: 

set input > 16 

CMS then translates all occurrences of the character > to X'16'. 

If you need to correct a line that contains backspaces, you can 
reverse the above sequence; alter the X*16» characters to asterisks and 
enter the CHANGE subcommand. 

2§fiBill£I 3 3270 Program Function Key, for Tab Settings 

You can set up a program function key to operate like a tab key on a 
typewriter terminal. You must use the CP SET command as follows: 

SET PFnn TAB n1 n2 . . . nn 
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where: 

PFnn is any valid function key from PF1 to PF12. 

n1 n2 . . . nn are the logical tab settings desired, expressed as 
decimal numbers. Invalid tat settings are ignored. You 
can specify the setting values in any order, but they 
are normally specified in ascending order. 

You can define different PF keys with different tab settings for 
different filetypes. Whenever you press the PF key you have set for a 
tab, the cursor moves to the corresponding position in the user input 
area, in much the same way that a typing element on a typewriter would 
move to the next tab stop. 

If you press the PF tab key to a position that already contains a 
data character, the data remains intact. If there is no data in that 
position, a tab character is entered in the file. The effect of the tab 
in the file depends, as in normal usage, on the image setting cf the 
editor. If the image setting is set to on (the default) , the tab expands 
to an appropriate number of blanks, to correspond to the settings in 
effect for the TABSET subcommand. When the TABSET settings match the 
tab settings of the PF key, then any lines you enter in the user input 
area appear exactly as they will appear in the output display area. 

If you tab beyond the last defined tat position, the cursor is 
repositioned at the beginning of the user input area. 

Changing and Dis£lay_in<j Special Characters 

When you edit a file on a 3270 terminal in display mode, you should not 
copy a line containing tabs or backspaces into the user input area. The 
tabs or backspaces are converted to blanks (X'UO 1 ). Similarly, if the 
line contains VM/370 logical line editing symbols that have been entered 
as data characters, the symbols are reinterpreted when you enter the 
line. 

If you use the SET OUTPUT function to display nonprintable characters 
in CMS, the character translations do not appear when the editor is in 
display mode. They are, however, displayed when the editor is in line 
mode. 



Using APL with a 3270 

If you have a 3277 display station equipped with an APL keyboard, you 
can use APL on a 3270 terminal in CMS. You invoke the APL virtual 
machine by issuing the command specified in the VSAPL Program Product 
documentation. This command invokes the VSAPL-CMS interface program. 
You are then prompted to press the APL On/Off key which is on your 
terminal; pressing this key changes the keyboard to APL character input 
mode. You are then prompted to press the Enter key to continue. 

EBCDIC or APL characters can always be displayed; the APL On/Off key 
does not change this. The VSAPL-CMS interface program issues the 
TERMINAL APL ON command for you and selects the appropriate translation 
tables. The interface program then invokes the VSAPL program. When the 
VSAPL ready message appears on the screen, you can use APL. 
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You can send a copy of your display screen to a locally or remotely- 
attached printer. Be sure that the printer you send your output to has 
the APL feature installed; if it does not, the APL characters are not 
printed. Most: system printers do not have an APL print chain; therefore 
you may need to use the copy function to direct your screen output 
displays to a 3284 or 3286 printer. 



ERROR SITUATIONS 

If you do not have the APL hardware feature installed on your 3270 but 
you invoke API: 

• The VSAPL program is invoked and the TERMINAL APL ON command is 
issued. 

• You cannot communicate with the VSAPL program. 

• Any APL characters that are written to the screen appear as blanks. 

If you have the APL feature installed on your terminal, but invoke 
APL manually without issuing the TERMINAL APL ON command or issue 
TERMINAL APL OFF at sometime during APL processing: 

• The VSAPL program is activated. 

• You cannot communicate with the VSAPL program. 

• Any APL characters written to the screen appear as blanks. 

If you attempt to use the APL 0/S (overstrike) key when the APL 
hardware key is set off, it acts as a backtab key and repositions the 
cursor to the beginning of the user input area. 



LEAVING THE APL ENVIRONMENT 

Issue the APL command 

) OFF 
to log off VM/370. 

Issue the APL command 

) OFF HOLD 

to return to CMS. This APL command invokes the VSAPL-CMS interface 
program, which 

• Issues the TERMINAL APL OFF command 

• Prompts you to press the APL hardware key 

• Returns to CMS 

Note: The APL hardware feature is a key, not a switch. Each time you 
press the APL key you reverse its on/off setting. To determine whether 
APL is on or off, press a key that represents a special APL character. 
If the character displayed is an APL character, the hardware APL feature 
is set on. If the character displayed is a non-APL character, you must 
press the APL key once to set the APL feature on. 
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Appendix D: Sample Terminal Sessions 



This appendix provides sample terminal sessions showing you how to use: 

The CMS Editor (using context editing), and the CMS COPYFILE, SORT, 
RENAME, and ERASE commands. 

The CMS Editor (using line-number editing) 

CMS OS simulation to create, assemble, and execute a program using OS 
macros in the CMS environment. 

CMS DOS/VS simulation to create, assemble, and execute a program 
using DOS/VS macros in the CMS/DOS environment. 

Access Method Services under CMS, to create VSAM catalogs and data 
spaces, and to use the define and repro functions of AMSERV. 
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Sample Terminal Session Using the Editor and CMS File System Commands 



This terminal session shows you how to create a CHS file and make changes to it using the 
CMS Editor, and then manipulate it using the CBS file system commands, COPYFILE, ERASE, 
RENAME, and SORT. 

Note: Throughout this terminal session whenever a TYPE subcommand or command is issued 
that results in a display of the entire file, the complete display is not shown; omitted 
lines are indicated by vertical ellipses (...)• When you enter the TYPE command or 
subcommand, you should see the entire display. 



O 

© 



edit comm 

NEW FILE: 

EDIT: 

image 

ON 

tabs 1 12 

trunc 72 

input 

INPUT: 

copyfile 

sort 

edit 

edit 

rename 

punch 

print 

erase 

listfile 

state 

statew 

readcard 

disk dump 

TRUNCATED 

DISK DUMP 

disk load 

compare 

tape dump 

tape load 

EDIT: 



and data 



80 



copy cms files 

sort cms files in alphameric order by specific columns 

create a cms file 

modify a cms file 

change the name of a cms file 

punch a copy of a cms file on cards 

print a cms file 

erase a cms file 

list information on a cms file 

verify the existence of a cms file 

verify the existence of a cms file on a read/write disk 

read a cms file from your card reader onto disk 

punch a cms file in cms disk dump format into your virtual card punch for 

PUNCH A CMS FILE IN CMS DISK DUMP FOEMAT INTO YOUR VIRTUAL CA 
read a disk dump file onto disk 
compare the contents of cms disk files 
dump cms files onto tape 
read cms files cnto disk from tape 



Qp Use the EDIT command to invoke the CMS Editor to create a file with a filename of 
COMMAND and a filetype of DATA. Since the file does not exist, the editor issues 

©the message NEW FILE. 
Check that the image setting is ON. This is the default for all filetypes except 
SCRIPT. Then, set the logical tab stops for this file at 1 , 12, and 80, and set a 

©truncation limit of 72. 
Enter the subcommand INPUT to enter input mode and begin entering lines in the file. 
For these input files, you should press the Tab key (or equivalent) on your terminal 
following each CMS command name. If there is a physical tab stop on your terminal 

Oin column 12, the input data appears aligned. 
The message, TRUNCATED, indicates that the line you just entered exceeded the 
truncation limit you set for the file (column 72) . The editor displays the line, so 
you can see how much of the line was accepted. Your virtual machine is still in 
^^ input mode, so continue entering input lines. 

^) To get out of input mode, enter a null line (press the Return or Enter key without 
entering any data). The editor responds with the message EDIT:. 
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o 

© 



© 

© 
© 



top 

TOF: 

type * 

TOF: 

COPYFILE COPY CMS FILES 



TAPE LOAD READ CMS FILES ONTO DISK FROM TAPE 

EOF: 

locate /disk dump 

DISK DUMP PUNCH A CMS FILE IN CMS DISK DUMP FORMAT INTO YOUR VIRTUAL CA 

replace disk dump punch a cms file onto cards 

input 

INPUT: 

type display the contents of a cms file at your terminal 

rename alter the name of a cms file 

sort resequence the records in a cms file 

copyfile reformat a file, by columns 

comprae verify that two files are identical 

EDIT: 

change /rae/are/ 

COMPARE VERIFY THAT TWO FILES ARE IDENTICAL 

bo 

TAPE LOAD READ CMS FILES ONTO DISK FROM TAPE 

input 

INPUT: 

EDIT: 

file 

R; 



ffj Use the TOP subcommand to position the current line pointer at the top of the file. 

^^ The editor responds TOF:. 

^p Use the TYPE subcommand to display the entire file. Note that all of your input 
lines are translated to uppercase characters, and that the tab characters you 
entered have been expanded, so that the first word following each command name 

— ^ begins in column 12. 

{p The message EOF: indicates that the end of the file is reached. You can issue the 
LOCATE subcommand to locate a line. since you are at the bottom of the file, the 
editor begins searching from the top of the file. Notice that you can enter the 
character string you want to locate in lowercase characters; the editor translates 

©it to uppercase to locate the line. The editor displays the line. 
Use the REPLACE subcommand to replace this line, in a shortened form so that it is 
not truncated. Remember to enter a tab character after the command name; when you 
enter the line, the tab stop does not have to be in column 12. Then, use the INPUT 
subcommand again to resume entering input. The lines that you enter next are written 
into the file following the DISK DUMP line. 
^^ When you make a spelling error or other mistake, you may want to correct it 
immediately. Enter a null line to return to edit mode, and use the CHANGE subcommand 
to correct the error. In this example, the string RAE is changed to ARE. The 

©editor displays the line as changed. 
Use the BOTTOM subcommand to move the current line pointer to point to the last line 
-^ in the file. Enter input mode with the INPUT subcommand. 

^^ If you enter input mode and decide that you do not want to enter input lines, all 
^^ you have to do to return to edit mode is enter a null line. 

qff To write the file onto disk, use the FILE subcommand. This writes it onto disk 
using the name with which you invoked the editor, COMMAND DATA. The CMS Ready 
message indicates that you are in the CMS command environment. 
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© 



type command data 



COPYFILE 
SORT 



COPY CMS FILES 

SORT CMS FILES IN ALPHAMERIC ORDER BY SPECIFIC COLUMNS 



© 

© 



TAPE LOAD READ CMS FILES ONTO DISK FROM TAPE 

R; 

edit command data 
EDIT: 



© 

© 
© 



© 



save 
EDIT: 

fnaie comm2 
file 

R; 

copyfile comm2 data a 

R; 

copyfile command data 

DMSCPY601R ENTER SPECIFICATION LIST: 

1-12 1 

R; 

type comm2 data 



(lovcase 

a comm2 data a (ovly specs 



COPYFILE 

SORT 

EDIT 

EDIT 

RENAME 

PUNCH 

PRINT 

ERASE 

LISTFILE 

ht 

R; 



Copy cms files 

Sort cms files in alphameric order by specific columns 

Create a cms file 

Modify a cms file 

Change the name of a cms file 

Punch a copy of a cms file on cards 

Print a cms file 

Erase a cms file 

List information on a cms file 



fl^ To display the entire file at your terminal, use the CMS TYPE command. Note any 
_. errors that you made that you might want to correct. 
(Q^ Use the EDIT command to edit the file COMMAND DATA again. This time, since the file 

©exists, the editor does not issue the message, NEW FILE: 
While you are in edit mode, make any changes that you need to; then issue the SAVE 
subcommand to save these changes, and replace the existing copy of the file onto 
^^ disk. 

^ Use the FNAME subcommand to change the filename of the file to COMM2 (the filetype 
remains unchanged) . When you issue the FILE subcommand this time, the file is 
^-j. written onto disk with the name C0MM2 DATA. 

Qj) You can rewrite the entire file, COMM2 DATA in lowercase characters, using the 
— v COPYFILE command with the LOWCASE option. 

U| The file C0MM2 DATA is now all lowercase characters (you can display the file with 
the TYPE command if you want to verify it) . However, the command names, and the 
first character of the description should be uppercase characters. You can use the 
COPYFILE command again, to overlay the original uppercase characters of COMMAND DATA 
in columns 1 through 12 over the lowercase characters in columns 1 through 12 of 
-. C0MM2 DATA. 

fjj Use the TYPE command to verify that the COPYFILE command did, in fact, overlay only 
_^ the columns that you wanted. 

^p The HT Immediate command suppresses the display of the remainder of the file; you 
can see from the first few lines that the format of the file is correct. 
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© 






G 



© 
© 



© 



listfile * data 
COMMAND DATA A1 
COMM2 DATA A1 

R; 

sort comm2 data a command sort a 
DMSSRT604R ENTER SOBT FIELDS: 
1 9 

R; 

type command sort 

COMPARE Verify that two files are identical 
COMPARE Compare the contents of cms disk files 



TYPE Display the contents of a cms file at your terminal 

R; 

copyfile comm2 data a function data a ( specs 

DMSCPY601R ENTER SPECIFICATION LIST: 

12-72 1 1-9 70 

R; 

type function data 

Copy cms files COPYFILE 

Sort cms files in alphameric order by specific columns SORT 



Read cms files onto disk from tape TAPE LOAD 

R; 

sort function data a function sort a 

DMSSRT604R ENTER SORT FIELDS: 

1 70 

R; 

type function sort 

Alter the name of a cms file RENAME 

Change the name of a cms file RENAME 



Verify the existence of a cms file on a read/write disk STATEW 

R; 



The LISTFILE command lists your two files with the filetype of DATA. (If you 

previously had files with these filetypes, they are also listed.) 

To sort the file COMM2 DATA into alphabetic order, by command, issue the SORT 

command. When you are prompted for the sort fields, enter the columns that contain 

the command names, 1 through 9. 

The output file from the SORT command is named COMMAND SORT. You can use the TYPE 

command to verify that the records are now sorted alphabetically by command. 

To create another copy of the file, this time with the command names on the right 

and the functional description on the left, use the COPYFILE command with the SPECS 

option again. To create a file this way, you must know the columns in your input 

file (C0MM2 DATA) and how you want them arranged in your output file (FUNCTION 

DATA). Columns 1 through 9 contain the command names; columns 12 through 72 contain 

the descriptions. The specification list entered after the prompting message 

indicates that columns 12 through 72 should be copied and placed beginning in column 

1, and that columns 1 through 9 should be copied beginning in column 70. 

Verify the COPYFILE operation with the TYPE command. 

Sort the file FUNCTION DATA so that the functional descriptions appear in alphabetic 

order. You may also want to display the output file, FUNCTION SORT. 
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© 



© 



DATA 
DATA 
SORT 



A1 
A1 
A1 
A1 
A1 



listfile 
COMMAND 
COMM2 
COMMAND 
FUNCTION DATA 
FUNCTION SORT 

R; 

erase command data 

R; 

rename coom2 data a command data a 

R; 

listfile * * a ( label 

FILENAME FILETYEE 

FUNCTION SORT 

COMMAND DATA 

COMMAND SORT 

FUNCTION DATA 

R; 

edit function sort 

EDIT: 

zone 

1 80 
zone 60 

change / // * 
Alter the name of a cms file 
Change the name of a cms file 



FM 


FORMAT 


RECS 


BLOCKS DATE 


TIME 


LABEL 


A1 


F 80 


22 


3 10/13/75 


7:52 


ABC191 


A1 


F 80 


22 


3 10/13/75 


7:48 


ABC191 


A1 


F 80 


22 


3 10/13/75 


7:48 


ABC191 


A1 


F 80 


22 


3 10/13/75 


7:51 


ABC191 



RENAME 
RENAME 



© 



Verify the existence of a cms file on a read/write disk 

EOF: 

top 

TOF: 

find List 

NOT FOUND 

EOF: 

case 

U 
case m 
find List 
List information on a cms file 



STATEW 



LISTFILE 



© 

© 



© 

© 



If these are the only files on your A-disk, the LISTFILE command entered with no 

operands produces a list of the files created so far. 

The file COMM2 was created for a workfile, in case any errors might have happened. 

Since you no longer need the original file, COMMAND DATA, you can erase it. 

Use the RENAME command to rename the workfile COMM2 DATA to have the name COMMAND 

DATA. The LISTFILE command verifies the change. 

To begin altering the file FUNCTION SORT, invoke the editor again. 

The ZONE command reguests a display of the current zone settings, which are columns 

1 and 80. When you issue the command ZONE 60, it changes the settings to columns 60 

and 80, so that you cannot modify data in columns 1 through 59. 

The CHANGE subcommand reguests that the first appearance of five consecutive blanks 

on each line in the file be compressed. The editor displays the results of this 

CHANGE reguest by displaying each line changed (which is each line in the file) . The 

net effect is to shift the command column 5 spaces to the left. 

Position the current line pointer at the top of the file, and then issue a FIND 

subcommand to move the line pointer to the line that begins with "List". 

The editor indicates that the line is not found. Checking the current setting for 

the CASE subcommand, you can see that it is U, or uppercase, which indicates that 

the editor is translating your input data to uppercase. You can issue the CASE M 

subcommand to change this setting, then reissue the FIND subcommand. 
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© 



change /on a cms/about a CMS 

NOT FOUND 

= zone 1 * 

List information about a CMS file 

top 

TOF: 

change /cms/CMS/ * 

Alter the name of a CMS file 

Change the name of a CMS file 



LISTFILE 



RENAME 
RENAME 



© 

© 

© 

© 



Verify the existence of a CMS file on a read/write disk 

EOF: 

save 

EDIT: 

top 

TOF: 

next 

Alter the name of a CMS file 

$dup 

Alter the name of a CMS file 

change /name/filetype/ 

Alter the filetype of a CMS file 

next 

Change the name of a CMS file 

change /name/filename/ 

Change the filename of a CMS file 

next 

Compare the contents of CMS disk files 

next 

Copy CMS files 

find M 

Modify a CMS file 

up 

List information about a CMS file 

i Make a copy of a CMS disk file 

top 

TOF: 



STATEW 



RENAME 
RENAME 

RENAME 
RENAME 

RENAME 

COMPARE 

COPY FILE 

EDIT 

LISTFILE 
COPYFILE 



© 

© 
© 



© 



The editor locates the line and displays it. You want to change the character string 

"on a cms" to "about a CMS". The editor does not find the string you specify because 

the zone setting for columns 60 through 80 is still in effect. You can enter the 

ZONE subcommand, and reissue the CHANGE subcommand, or you can enter the = (REUSE) 

subcommand to stack the CHANGE subcommand, and enter the ZONE subcommand to execute 

first. 

The ZONE subcommand is executed, then the CHANGE subcommand. The editor displays the 

changed line. 

At the top of the file, enter another global change reguest, to change lowercase 

occurrences of the string cms to uppercase. The editor displays each line changed. 

When the EOF: message indicates that the end of the file is reached, you can save 

the changes made during this edit session with the SAVE subcommand before 

continuing. 

Move the current line pointer to point to the first line in the file. You want to 

add an entry that is similar; use the $D0P edit macro to duplicate the line, then 

change the copy that you made of the line. 

You can change the word name to filename in the next line also. 

You can scan a file, a line at a time, by issuing successive NEXT subcommands. 

To insert a line beginning with the character M, and to maintain alphabetic 

seguencing, use the FIND subcommand to find the first line beginning with an M. The 

line to be inserted begins with the characters MA, so you want to move the line 

pointer up. 

You can insert a single line into a file with the INPUT subcommand. Here, the INPUT 

subcommand is truncated to I, so that when you space over to write the command name 

in the right column, you can align it (you only have to allow for the two character 

spaces use by "i " . 
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© 



/COPYFILE 

Copy CMS files 

n 

Create a CMS file 

n 

Display the contents of a CMS file at your terminal 

n 

Dump CMS files onto tape 

n 

Erase a CMS file 

up 3 

Create a CMS file 

i Delete a file from a CMS disk 

file 

H; 

type function sort a 

Alter the name of a CMS file 
Alter the filetype of a CMS file 
Change the filename of a CMS file 



COPYFILE 

EDIT 

TYPE 

TAPE DUMP 

ERASE 

EDIT 
ERASE 



RENAME 

RENAME 
RENAME 



Verify the existence of a CMS file on a read/write disk 

^1 edit function sort 
zone 58 

change / // * * 
Alter the name of a CMS file 
Alter the filetype of a CMS file 
Change the filename of a CMS file 



STATEW 



RENAME 
RENAME 
RENAME 



Verify the existence of a CMS file on a read/write disk STATEW 

sm. EOF: 

© top 
TOP: 

change //I / * 

Alter the name of a CMS file I RENAME 

Alter the filetype of a CMS file I RENAME 

Change the filename of a CHS file I RENAME 



Verify the existence of a CMS file on a read/write disk | STATEW 
EOF: 



© 

8 



© 



Move the line pointer to the top of the file and begin scanning again. A diagonal 

(/) is interpreted as a LOCATE subcommand. 

The NEXT subcommand can be truncated to "N". 

In front of the line beginning "Display", insert a line beginning with "Delete". If 

you want to make any other modifications, do so. Otherwise, write this file onto 

disk with the FILE subcommand. 

Verify your changes. 

Edit the file again. To compress unnecessary spaces in right hand columns, change 

the zone setting. This time, issue a CHANGE subcommand that will delete all blank 

spaces occuring after column 58. Since some changes you made to the file might have 

spoiled the alignment in the command column, this CHANGE subcommand should realign 

all of the columns. 

Return the current line pointer to the top of the file. Change a null string to the 

string "| " for all lines in the file; since the left zone is still column 58, the 

characters are inserted in columns 58 and 59. 
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zone 1 * 

top 

TOP: 

c //I / * 

| Alter the name of a CMS file 

| Alter the filetype of a CMS file 

| Change the filename of a CMS file 



| RENAME 
| RENAME 
I RENAME 



I Verify the existence of a CMS file on a read/write disk 

©EOF: 
top 
TOP: 
next 

| Alter the name of a CMS file 
tabset 72 
repeat * 
overlay | 

| Alter the name of a CMS file 
| Alter the filetype of a CMS file 
| Change the filename of a CMS file 
| Compare the contents of CMS disk files 



| STATEW 



I RENAME 



I RENAME 
| RENAME 
I RENAME 
I COMPARE 



s 



© 



I Verify the existence of a CMS file on a read/write disk | STATEB | 

EOF: 

bottom 

| Verify the existence of a CMS file on a read/write disk | STATES | 
input 
zone 1 72 
c / /-/ 1 * 

top 

TOP: 

input 

c / /-/ 1 * 



© file 
R; 



print function sort 
R; 



^p Change the left zone setting to column 1 and let the right zone be equal to the 
record length; issue the CHANGE subcommand to insert the "I" in columns 1 and 2. 

j^ CHANGE can be abbreviated as "C". 

^I At the top of the file, change the TABSET subcommand setting to 72. This makes 
column 72 the left margin. The REPEAT * subcommand, followed by the OVERLAY 
subcommand, indicates that all the lines in the file are to be overlayed with a | in 

^^ the leftmost column (column 72) . 

^J When you enter this INPUT subcommand, enter a number of blank spaces following it; 

©this places a blank line in the file. 
Reset the ZONE setting to columns 1 and 72. The CHANGE subcommand indicates that all 
blanks on this line should be changed to hyphens (-) . Only the blanks within the 
gm± specified zone are changed. 

IjfiJ Insert another blank line at the top of the file and change it to hyphens. 
Ijfa Write the file onto disk and use the CMS PRINT command to spool a copy to the 
^^ offline printer. 
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Sample Terminal Session Using Line-Number Editing 



This terminal session shows how a terminal session using right-handed line-number editing 
might appear on a typewriter terminal. The commands function the same way on a display 
terminal, but the display is somewhat different. When you enter these input lines, you 
should have physical tab stops set at your terminal at positions 16 and 22 (for assembler 
columns 10 and 16; the difference compensates for the line numbers, as you will see). On 
a display terminal, tab settings have no significance; once the line is in the output 
display area, it has the proper number of spaces. 



© 



O 

© 



o 
© 

o 
o 



edit test i 


assemble 


HEW FILE: 






EDIT: 








line mode right 




input 








INPUT: 








00010 


* sample 


of linemode rig 


00020 


test 




csect 


00030 






balr 12,0 


00040 






using *, 12 


00050 






st 14,sav14 


00060 






wrterm testing. 


00070 






1 14,sav14 


00080 






br 14 


00090 






end 


00100 








EDIT: 








60 








00060 






WRTEBM 



TESTING... 
c /testing. . ./'testing. .. ' 

00060 WRTEBM 'TESTING... 1 

80 

00080 BR 14 

input 
INPUT: 



Use the EDIT command to invoke the CMS Editor. Since this is a new file, the editor 

issues the NEW FILE message. 

Issue the LINEMODE subcommand to indicate that you want to begin line-number 

editing. For ASSEMBLE files, you cannot have line numbers on the left, because the 

assembler expects data in columns 1 through 7. 

As soon as you issue the INPUT subcommand, the editor begins prompting you to enter 

input lines. For convenience in entering lines, the line numbers appear on the left, 

as they would if you were using left-handed line-number editing. In your ASSEMBLE 

file, however, the line numbers are actually on the right. 

When you are have finished entering these input lines, enter a null line to return 

to edit mode from input mode. 

To locate lines when you are using line-number editing, you can enter the line 

number of the line. In this case, enter 60 to position the current line pointer at 

the line numbered 00060. The editor displays the line. 

Issue the CHANGE subcommand to place quotation marks around the text line for the 

WRTERM macro. The editor redisplays the line, with the change. 

Issue the nnnnn subcommand, specifying line number 80, and use the INPUT subcommand 

so you can begin entering more input lines. 
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$ 

© 



o 



© 



00083 sav14 


ds 


f 


00085 wkarea 


ds 


3d 


00087 flag 


ds 


X 


00088 runon 


egu 


x'80» 


00089 runoff 


egu 


x'40' 


RENUMBER LINES 






EDIT: 






linemode off 






serial on abc 






save 






EDIT: 






linemode right 






type 






00030 HOHOFF 


EQU 


X^O* 


verify 1 * 






type 






00030 RUNOFF 


EQU 


X'40' 


135 


runmix egu x'20' 


50 






00050 


ST 


14,SAV14 


input 






INPUT: 






00053 


tm 


flag, runon 


00055 


bcr 


1,14 


00057 






EDIT: 






top 






TOF: 






next 






* SAMPLE OF LINEMODE RIGHT 


restore 







ABC00130 
ABC00050 



ABC00010 



o 
o 



8 

© 

© 



© 
© 

© 



When you begin entering input lines between two existing lines, the editor uses an 

algorithm to assign line numbers. 

The editor ran out of line numbers, since the next line in the file is already 

numbered 90. You must renunber the lines. Before you can renumber the lines, you 

must turn line-number editing off. Before issuing the SAVE subcommand, which writes 

the file and its new line numbers onto disk, you can issue the SERIAL subcommand. 

SERIAL ABC indicates that you want the characters ABC to appear as the first three 

characters of each serial number. 

The EDIT message indicates that the SAVE reguest has completed. 

Issue the LINEMODE subcommand to restore line-number editing. Use the TYPE 

subcommand to verify the position of the current line pointer. 

If you want to see the serial numbers in columns 72 through 80, issue the VERIFY 

subcommand, specifying *, or the record length. Normally, the editor does not 

display the columns containing serial numbers while you are editing. 

You can use the nnnnn subcommand to insert individual lines of text. This subcommand 

inserts a line that you want numbered 135, and places it in its proper position in 

the file. Note that although, in this example, the current line pointer is 

positioned at line 130, it does not need to be at the proper place in the file. When 

the subcommand is complete, however, the current line pointer is positioned 

following the line just inserted. 

Position the line pointer at the line numbered 50, and again begin entering the 

input lines indicated. 

Enter a null line to return to edit mode, move the current line pointer to the top 

of the file, and display the first line. 

The RESTORE subcommand restores the default settings of the editor, and the the 

verification columns are restored to 1 and 72, so that line numbers are not 

displayed in columns 72 through 80. 
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type * 






* SAMPLE 


OF LINEMODE RIGHT 


TEST 


CSECT 






BALR 


12,0 




USING 


*,12 




ST 


14,SAV14 




TM 


FLAG, RUNON 




BCR 


1,14 




WRTERM 




L 


14,SAV14 




BR 


14 


SAV14 


DS 


F 


WKAREA 


DS 


3D 


FLAG 


DS 


X 


RUNON 


EQU 


X«80» 


RUNOFF 


EQU 


X'40« 


RUNMIX 


EQU 
END 


X«20« 


EOF: 






file 






RESERIALIZATION SUPPRESSED 


k; 






type test assemble 


* SAMPLE 


OF LINEMODE RIGHT 


TEST 


START 


X'20000" 




BALR 


12,0 




USING 


*,12 




ST 


14,SAV14 




TM 


FLAG, RUNON 




BCR 


1,14 




TYPE 


•TESTING.. . 




L 


14,SAV14 




BR 


14 


SAV14 


DS 


F 


WKAREA 


DS 


3D 


FLAG 


DS 


X 


RUNON 


EQU 


X'80» 


RUNOFF 


EQU 


X«40» 


RUNMIX 


EQU 
END 


X'20« 



•TESTING... • 



ABC00010 
ABC00020 
ABC00030 
ABC00040 
ABC00050 
00053 
00055 
ABC00060 
ABC00070 
ABC00080 
ABC00090 
ABC00100 
ABC00110 
ABC00120 
ABC00130 
00135 
ABC00140 



lD Use the TYPE subcommand to display the file. 

ff| When you issue the FILE subcommand to write the file onto disk, the editor issues 

^^ the message RESERIALIZATION SUPPRESSED to indicate that it is not going to update 

the line numbers, so that the current line numbers match the line numbers as they 
^-. existed when the SAVE subcommand was issued. 
U| If you want to see how the file exists on disk, use the CMS TYPE command to display 

the file. Note that the lines inserted after the SAVE subcommand do not have the 

initial ABC characters, and that they retain the line numbers they had when they 

were inserted. 
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Sample Terminal Session for OS Programmers 



The following terminal session shows how you might create an assembler language program 
in CMS, assemble it, correct assembler errors, and execute it. All the lines that appear 
in lowercase are lines that you should enter at the terminal. Uppercase data represents 
the system response that you should receive when you enter the command. 

The input data lines in the example are aligned in the proper columns for the 
assembler; if you are using a typewriter terminal, you should set your terminal's tab 
stops at columns 10, 16, 31, 36, 41, and 46, and use the Tab key when you want to enter 
text in these columns. If you are using a display terminal, when you use a PF key defined 
as a tab, or some input character, the line image is expanded as it is placed in the 
screen output area. 



There are some errors in the terminal session, 
errors in CMS. 



so that you can see how to correct 



^J edit ostest assemble 


NEW FILE 


: 




EDIT: 






input 






INPUT: 






dataproc 


csect 






print 


nogen 




space 




rO 


equ 





r1 


equ 


1 


r2 


equ 


2 


no 


equ 


10 


r12 


equ 


12 


r13 


equ 


13 


r14 


equ 


14 


r15 


equ 
space 


15 




stm 


r14,r12,12 (r 




balr 


r12,0 




using 


*,r12 




St 


r 13,savearea 




la 


r15,savearea 




St 


r15,8 (r13) 




lr 


r13,r15 




space 




♦open fi 


les an< 
space 


3 check that 




la 


r3,0 




open 


(indata,outd 




using 


ihadcb,r10 




la 


r10,indata 




tm 


dcboflgs,x' 1 




bnz 


checkout 




la 


r3,100 




b 


exit 


checkout 


la 


r10,outdata 




tm 


dcboflgs,x' 1 




bnz 


process 




la 


r3,200 




b 


exit 



13) save caller's regs 
establish 

addressability 

+4 store addr of caller's savearea 
get the address of my savearea 
store addr in caller's savearea 
save addr of my savearea 

they opened okay 

initially set return code 
ata, (output) ) open files 

get dsect to check files 

prepare to check output file 
0' everything ok? 

. . .continue 

set return code 

... ex it 

check output file 
0' is it okay? 

» . . 

set return code 



The EDIT command is issued to create a file named OSTEST ASSEMBLE. Since the file 
does not exist, the editor indicates that it is a new file and you can use the INPUT 
subcommand to enter input mode and begin entering the input lines. 
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© 



process 



exit 



space 
egu 
get 
lr 
put 
b 

space 
equ 
close 
1 

lr 
1 

lm 
br 

space 
savearea dc 
indata deb 

EDIT: 

$mark 

save#input 

EDIT: 

INPUT: 



outdata 



deb 
debd 
space 
end 



* 

indata 

r2,r1 

outdata, (2) 

process 



read a record from input file 
save address of record 
move it to output 
continue until end-of-file 



(indata, ,outdata) close files 

r 13,savearea+4 addr of callers save area 

r15,r3 load return code 

r14,12(r13) get return address 

rO,r 12,20 (r13) restore regs 

r14 bye... 

18f »0» 

ddname=indd, macrf=gl,dsorg=ps,recfm=f ,lrecl=80. 



eodad=exit 
ddname=outdd,macrf=pm, dsorg=ps 



© 
O 



EDIT: 

file 

R; 

global maclib osmacro 

assemble ostest 

* 

* 



^p Since the DCB macro statement takes up more than one line, you have to enter a 
continuation character in column 72. To do this, you can enter a null line to return 
to edit mode and execute the SHARK edit macro, which places an asterisk in column 
72., If the SHARK edit macro is not on your system, you will have to enter a 
continuation character some other way. (See "Entering a Continuation Character in 

-^ Column 72" in "Section 5. The CHS Editor.") 

^p Before continuing to enter input lines, the EDIT subcommand SAVE is issued to write 
what has already been written onto disk. The CP logical line end symbol (#) 

-^ separates the SAVE and IHPUT subcommands. 

^p A null line returns you to edit mode. You may wish, at this point, to proofread 
your input file before issuing the FILE subcommand to write the ASSEHBLE file onto 

-^ disk. 

^p Since this assembler program uses OS macros, you must issue the GLOBAL command to 
identify the CHS macro library, OSHACRO HACLIB, before you can invoke the 

-^ assembler. 

(p The ASSEHBLE command invokes the VH/370 assembler to assemble the source file; the 
asterisks (*) indicate the CHS blip character, which you may or may not have made 
active for your virtual machine. 
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INITIALLY SET RETURN CODE 



o 



© 

© 

© 



ASSEMBLER DONE 

OST00230 23 LA R3,0 

IF0188 R3 IS AN UNDEFINED SYMBOL 

OST00240 24 OPEN (INDATA,CUTDATA, (OUTPUT) ) OPEN FILES 

4000000 27+ 12,*** IHB002 INVALID OPTION OPERAND SPECIFIED-OUTDATA 
IF0197 *** MNOTE *** 

OST00290 32 LA R3,100 SET RETURN CODE 

IF0188 R3 IS AN UNDEFINED SYMBOL 

OST00340 37 LA R3,200 SET RETURN CODE 

IF0188 R3 IS AN UNDEFINED SYMBOL 

OST00460 63 LR R15,R3 LOAD RETURN CODE 

IF0188 R3 IS AN UNDEFINED SYMBOL 

NUMBER OF STATEMENTS FLAGGED IN THIS ASSEMBLY = 5 
R(00012) ; 

edit ostest assemble 
locate /r2 
R2 EQU 2 
i r3 equ 3 
/open 



OPEN 
OPEN 



(INDATA,OUTDATA, (OUTPUT)) 
(INDATA,,OUTDATA, (OUTPUT)) 



OPEN FILES 
OPEN FILES 



file 

R; 

assemble ostest 

* 

* 

* 
* 

ASSEMBLER DONE 

NO STATEMENTS FLAGGED IN THIS ASSEMBLY 

R; 

filedef indd disk test data a 

R; 

filedef outdd punch 

R; 

#cp spool punch to * 



O 
O 

o 

© 
© 



© 

© 



The assembler displays errors encountered during assembly. Depending on how 

accurately you copied the program in this sample session, you may or may not receive 

some of these messages; you may also have received additional messages. 

You must edit the file OSTEST ASSEMBLE and correct any errors in it. The errors 

placed in the example included a missing comma on the OPEN macro, and the omission 

of an EQU statement for a general register. These changes are made as shown. The 

CMS Editor accepts a diagonal (/) as a LOCATE subcommand. 

After all the changes have been made to the ASSEMBLE file, you can issue the FILE 

subcommand to replace the existing copy on disk, and then reassemble it. 

This time, the assembler completes without encountering any errors. If your 

ASSEMBLE file still has errors, you should use the editor to correct them. 

The FILEDEF command is used to define the input and output files used in this 

program. The ddnames INDD and OUTDD, defined in the DCBs in the program, must have a 

file definition in CMS. To execute this program, you should have a file on your 

A-disk name TEST DATA, which must have fixed-length, 80-character records. If you 

have no such file, you can make a copy of your ASSEMBLE file as follows: 



copyfile ostest assemble a test data a 

punch file, so 



that it will be written to your 



The output file is defined as a 

virtual card punch. 

The CP SPOOL command is issued, using the #CP function, to spool your virtual punch 

to your virtual card reader. When you use the #CP function, you do not receive a 

Ready message. 
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© 
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load ostest 

B; 

start 

DHSLI0740I EXECUTIOH BEGINS... 

DHSSOP036E OPEN ERROR CODE «04» ON 'OUTDD ■ . 

R (00200) ; 

filedef 

I HDD DISK TEST EAT A A1 

OUTDD PUNCH 

R; 

filedef outdd punch (lrecl 80 recfm f 

RJ 

#cp query reader all 

NO RDR FILES 

load ostest (start 

DHSLI0740I EXECUTION BEGINS... 

PUN FILE 6198 TO BILBO COPY 01 NOHOLD 

B; 

fi indd reader 

B; 

fi outdd disk new osfile a4 (recfn fb block 1600 lrecl 80 

B; 

listfile nev osfile a4 (label 

DHSLST002E FILE NOT FOUND. 

R (00028) ; 

run ostest 

EXECUTION BEGINS... 

* 

B; 

listfile new osfile a4 (label 

FILENAME FILETYPE FM FORMAT RECS BLOCKS DATE TIME LABEL 

NEW OSFILE A4 F 1600 5 10 9/30/75 8:26 PAT198 



The LOAD command loads the TEXT file produced by the assembly into virtual storage. 

The START command begins program execution. 

An open error is encountered during program execution. The CMS Ready message 

indicates a return code of 200, which is the value placed in it by your program. 

The FILEDEF command, with no operands, results in a display of .the current file 

definitions in effect. 

Error code 4 on an open request means that no RECFM or LRECL information is 

available. An examination of the program listing would reveal that the DCB for 

OUTDD does not contain any information about the file format; you must supply it on 

the FILEDEF command. Re-enter the FILEDEF command. 

You can use the CP QUERY command to determine whether there are any files in your 

card reader. It should be empty; if not, determine whether they might be files you 

need, and if so, read them into your virtual machine; otherwise, purge them. 

Use the LOAD command to execute the program again; this time, use the START option 

of the LOAD command to begin the program execution. 

The PUN FILE message indicates that a file has been transferred to your virtual card 

reader. The Ready message indicates that your program executed successfully. 

For the next execution of this program, you are going to read the file back out of 

your card reader and create a new CMS disk file, in OS simulated data set format. 

FI is an acceptable system truncation for the command name, FILEDEF. 

The LISTFILE command is issued to check that the file NEW OSFILE does not exist. 

The RUN command (which is an EXEC procedure) is used instead of the LOAD and START 

commands, to load and execute the program. The Ready message indicates that the 

program completed execution. 

The LISTFILE command is issued again, and the file NEW OSFILE is listed. (If you 

issue another CP QUERY READER command, you will also see that the file is no longer 

in your card reader.) 
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The following terminal session shows how you might create an assembler language program 
in CMS* assemble it, correct assembler errors, and execute it. all the lines that appear 
in lowercase are lines that you should enter at the terminal. Uppercase data represents 
the system response that you should receive when you enter the command. 

The input data lines in the example are aligned in the proper columns for the 
assembler; if you are using a typewriter terminal, you should set your terminal's tab 
stops at columns 10, 16, 31, 36, 41, and 46 and use the Tab key when you want to enter 
text in these columns. If you are using a display terminal, when you use a PF key or an 
input character defined as a tab, the line image is expanded as it is placed in the 
screen output area. 

Note: The assembler, in CMS, cannot read macros from DOS/VS libraries. This sample 
terminal session shows how to copy macros from DOS/VS libraries and create CMS MACLIB 
files. Ordinarily, the macros you need should already be available in a system MACLIB 
file. You do not have to create a MACLIB each time you want to assemble a program. 



There are some errors in 
errors in CMS. 



the terminal session, so that you can see how to correct 



cp link dosres 130 130 rr linkdos 
DASD 130 LINKED R/0 

R; 

access 130 z 

Z (130) R/0 - DOS 

R; 

set dos on z 

R; 

edit dostest assemble 

NEW FILE: 



EDIT: 






input 






INPUT: 






begpgm 


csect 






balr 


12,0 




using 


*,12 




la 


13,savearea 




open 


infile, outfile 


loop 


get 


infile 




put 


outfile 




b 


loop 


eodad 


egu 


♦ 




close 


infile, outfile 




eoj 






eject 




buffer 


dc 


CL80« • 


infile 


dtfdi 


modname=shrmod,ioarea1=buffer,devaddr=sysipt. 



^P Use the CP LINK command to link to the DOS system residence volume and the ACCESS 
command to access it. In this example, the system residence is at virtual address 
— ^ 130 and is accessed as the Z-disk. 
^p Enter the CMS/DOS environment, specifying the mode letter at which the DOS/VS system 

©residence is accessed. 
Use the EDIT command to create a file named DOSTEST ASSEMBLE. Since the file does 
not exist, the editor indicates that it is a new file and you can use the INPUT 
subcommand to enter input mode and begin entering the input lines. 



Sample Terminal Session for DOS Programmers 355 



o 
e 



© 



© 

8 

o 
o 



© 



EDIT: 

$mark 

save#input 

EDIT: 

INPUT: 

eofaddr=eodad,recsize=80 
outfile dtfdi modname=shrmod,ioarea1= : buf fer ,devaddr=syspch. 





EDIT: 






$mark 






save#input 




EDIT: 






INPUT: 


recsize=81 




shrmod 


dimod typefle=output 




endpgm 


equ * 


o 


EDIT: 
file 


end 


o 


edit getmacs eserv 



NEW FILE: 

EDIT: 

tabs 2 72 

input 

INPUT: 

punch open, close, get, put, dimod , dtfdi 

EDIT: 

file 

B; 

assgn sysipt a 

B; 

eserv getmacs 

B; 



Since the DTFDI macro statement takes up more than one line, you have to enter a 

continuation character in column 72. To do this, you can enter a null line to return 

to edit mode and execute the $MARK edit macro, which places an asterisk in column 

72. If the $MARK edit macro is not on your system, you will have to enter a 

continuation character some other way. (See "Entering a Continuation Character in 

Column 72" in "Section 5. The CMS Editor.") 

Before continuing to enter input lines, the EDIT subcommand SAVE is issued to write 

what has already been written onto disk. The CP logical line end symbol (#) 

separates the SAVE and INPUT subcommands. 

Another continuation character is needed. 

A null line returns you to edit mode. You may want, at this point, to proofread your 

input file before issuing the FILE subcommand to write the ASSEMBLE file on disk. 

To obtain the macros you need to assemble this file, use the editor to create an 

ESERV file. By setting the logical tabs at columns 2 and 72, you can protect 

yourself from entering data in column 1. 

PUNCH is an ESERV program control statement that copies and de-edits macros from 

source statement libraries; in this case, the system source statement library. The 

output is directed to the SYSPCH device, which the CMS/DOS ESERV EXEC assigns by 

default to your A-disk. 

You must assign the logical unit SYSIPT before you invoke the ESERV command. GETMACS 

is the filename of the ESERV file containing the ESERV control statements. 



356 IBM VM/370: CMS User's Guide 



© 



© 

© 
© 

© 



© 



© 



© 



© 
© 

© 
© 

© 

© 
© 

© 



listfile getmacs * 

GETMACS ESERV A1 

GETMACS MACRO A1 

GETMACS LISTING A1 

R; 

sac lib gen dosmac getmacs 

R; 

erase getaacs * 

R; 

global oacllb dosmac 

R; 

assemble dostest 

* 

* 

ASSEMBLER DONE 

DOS00040 4 LA 13,SAVEAREA 

IF0188 SAVEAREA IS AN UNDEFINED SYMBOL 

DOS00110 35 EOJ 

IF0078 UNDEFINED OP CODE 

NUMBER OF STATEMENTS FLAGGED IN THIS ASSEMBLY = 

R (00008) ; 

edit dotest assemble 

EDIT: 

locate /buffer/ 

BUFFER DC CL80» • 

input savearea ds 9d 

file 

R ; 

edit eoj eserv 

NEW FILE: 

EDIT: 

i punch eoj 

file 

R; 

listio sysipt 
SYSIPT DISK A 

R; 

eserv eoj 

R; 



After the ESERV EXEC completes execution, you have three files. You may want to 

examine the LISTING file to check the ESERV program listing. The MACRO file 

contains the punch (SYSPCH) output. 

The HACLIB command creates a macro library named DOSMAC MACLIB. Since the MACLIB 

command completed successfully, you can erase the files GETMACS ESERV, GETMACS 

LISTING, and GETMACS MACRO; an asterisk in the filetype field of the ERASE command 

indicates that all files with the filename of GETMACS should be erased. 

Before you can invoke the assembler, you have to identify the macro library that 

contains the macros; use the GLOBAL command, specifying DOSMAC MACLIB. 

The ASSEMBLE command invokes the VM/370 assembler to assemble the source file; the 

asterisks (*) indicate the CMS blip character, which you may or may not have made 

active for your virtual machine. 

The assembler displays errors encountered during assembly. Depending on how 

accurately you copied the program in this sample session, you may or may not receive 

some of these messages; you may also have received additional messages. 

To correct the first error, which was the omission of a DS statement for SAVEAREA, 

edit the file DOSTEST ASSEMELE and insert the missing line. 

The second error indicates that the macro EOJ is not available, since it was not 

copied from the source statement library. Create another ESERV file to punch this 

macro. 

Use the LISTIO command to check that SYSIPT is still assigned to your A-disk, so 

that you do not have to issue the ASSGN command again. Then issue the ESERV command 

again, this time specifying the filename EOJ. 
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^J maclib add dosmac eoj 
H; 
naclib map dosmac (term 





MACRO 


INDEX SIZE 




OPEN 


2 43 




CLOSE 


46 43 




GET 


90 56 




PUT 


147 93 




DIMOD 


241 647 




DTFDI 


889 284 




EOJ 


1174 6 


4Vt 


E; 




© 


erase eoj 


* 




R; 






assemble 

* 

* 


dostest 


© 


* 
ASSEMBLES 


DONE 




NO STATEMENTS FLAGGE 


© 


R; 
listf ile 


dostest * 



dostest assemble a1 

dostest listing a1 

dostest text a1 
r; 

print dostest listing 



© 


doslked 


dostest 




© 


R; 

listfile 


dostest * 






DOSTEST 


ASSEMBLE 


A1 




DOSTEST 


DOSLIB 


A1 




DOSTEST 


TEXT 


A1 




DOSTEST 


LISTING 


A1 




DOSTEST 


MAP 


A5 




R; 







© Use the ADD function of the MACLIB command to add the macro EOJ to DOSMAC MACLIB. 
Then, issue the MACLIB command again, using the MAP function and the TERM option to 
^-. display a list of the macros in the library. 

^^ Erase the EOJ files. You should always remember to erase files that you do not need 
_^ any longer. Reassemble the program. 
^) This time, the assembler completes without encountering any errors. If your 

©ASSEMBLE file still has errors, you should use the editor to correct them. 
Use the LISTFILE command to check for DOSTEST files. The assembler created the 

files, DOSTEST LISTING and DOSTEST TEXT. The TEXT file contains the object module. 

You can print the program listing, if you want a printed copy. Then, you may want to 
-«. erase it. 
@ Use the DOSLKED command to link-edit the TEXT file into an executable phase and 

write it into a DOSLIB. Since this program has no external references, you do not 
._. need to add any linkage editor control statements. 
\Q Now, you have a DOSTEST DOSLIB, containing the link-edited phase, and a MAP file, 

containing the linkage editor map. You can display the linkage editor map with the 

TYPE command, or use the PRINT command if you want a printed copy. 
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#cp spool punch to * 

punch test data a 

PUN FILE 0100 TO BILBO COPY 01 HOHOLD 

R; 

#cp query reader all 

ORIGINID FILE CLASS RECDS CPY HOLD DATE TIME NAME TYPE DIST 

PATTI 5840 A PUN 000097 01 NONE 09/29 15:00:39 TEST DATA BIN211 

assgn sysipt reader 

R; 

assgn syspch a 

R; 

dlbl outfile a cms punch output (syspch 

R; 

state punch output a 

DMSSTT002E FILE NOT FOUND. 

R (00028) ; 

global doslib dostest 

R; 

fetch dostest 

DMSFET710I PHASE 'DOSTEST' ENTRY POINT AT LOCATION 020000. 

R; 

start 

DMSLI0740I EXECUTION BEGINS... 

R; 

listfile punch output a (label 

filename filetype fm format recs blocks date time label 
punch output a1 f 80 97 10 9/29/75 14:50 bbb191 
r; 

#cp query reader all 
NO RDR FILES 



To execute this program in CMS/DOS, punch a file that has fixed-length 80-character 
records into your virtual card punch. If you do not have any files that have 
fixed-length, 80-character records, you can create a file named TEST DATA with the 
CMS Editor, or by copying your ASSEMBLE source file with the COPYFILE command, as 
follows: 

copyfile dostest assemble a test data a 

Use the CP SPOOL command to spool the punch to your own virtual machine, then use 

the PUNCH command to punch the file. The PUN FILE message indicates that the file 

is in your card reader. Use the CP QUERY command to check that it is the first, or 

only file in your reader. 

Use the ASSGN command to assign SYSIPT to your card reader and SYSPCH to your 

A-disk. 

When you assign a logical unit to a disk mode, you must issue the DLBL command to 

identify the disk file to CMS. For this program execution, you are creating a CMS 

file named PUNCH OUTPUT. The STATE command ensures that the file does not already 

exist. If it does exist, rename it, or else use another filename or filetype on the 

DLBL command. 

Use the GLOBAL command to identify the DOSLIB, DOSTEST, you want to search for 

executable phases, then issue the FETCH command specifying the phase name. The 

FETCH command loads the executable phase into storage. When the FETCH command is 

executed without the START option, a message is displayed indicating the entry point 

location of the program loaded. 

The START command begins program execution. The CMS Ready message indicates that 

your program completed successfully. You can check the input and output activity by 

using the LISTFILE command to list the file PUNCH OUTPUT. If you use the CP QUERY 

command, you can see that the file is no longer in your virtual card reader. 
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ml assgn sysipt a 

dibl infile a ens punch output (sysipt 

B;; 

assgn syspch punch 

OR; 
fetch dostest (start 
— . DHSLI0740I EXECUTION BEGINS... 
© PUN FILE 5829 TO BILBO COPY 01 NOHOLD 

R; 

read punch2 output 

R; 

listfile punch2 output a (label 

FILENAME FILETYPE FM FORMAT RECS BLOCKS DATE TIME LABEL 

PUNCH2 OUTPUT A1 F 80 97 10 9/29/75 14:50 BBB191 

R; 



^j) If you want to execute this program again, you can assign SYSIPT and SYSPCH to 
different devices; in this example, the input disk file PUNCH OUTPUT is written to 
the virtual punch. You do not need to reissue the GLOBAL DOSLIB command; it remains 

^-. in effect until you reissue it or IPL CMS again. 

Q) This time, the program execution starts immediately, because the START option is 

_^ specified on the FETCH command line. 

^p Again, the PUN FILE message indicates that a file has been received in your virtual 
card reader. You can use the CMS command READCABD to read it onto disk and assign it 
a filename and filetype, in this example, PUNCH2 OUTPUT. 
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This sample terninal session shows you how to use Access Method Services under CMS. You 
should have an understanding of VSAM and Access Method Services before you use this 
terminal session. 

The terminal session uses a number of CMS files, which you may create during the 
course of the terminal session; or, you may prefer to create all of the files that you 
need before-hand. Within the sample terminal session, the file that you should create is 
displayed prior to the commands that use it. 

This terminal session is for both CMS OS VSAM programmers and CMS/DOS VSAM 
programmers; all the ASSGN commands and SYSxxx operands that apply when the CMS/DOS 
environment is active are shaded. If you have issued the command SET DOS ON, you must 
enter the shaded entries; if not, you must omit the shaded entries. 

Botes; 

1. This terminal session assumes that you have, to begin with, a read/write CMS A-disk. 
This is the only disk reguired. Additional disks used in this exercise are temporary 
disks, formatted with the IBCDASDI disk initialization program under CMS. If you 
have OS or DOS disks available, you should use them, and remember to supply the 
proper volume and virtual device address information, where appropriate. The number 
of cylinders available to users for temporary disk space varies among installations; 
if you cannot acguire ample disk space, see your system support personnel for 
assistance. 

2. Output listings created by AMSERV take up disk space, so if your A-disk does not 
have a lot of space on it, you may want to erase the LISTING files created after 
each AMSERV step. 

3. If any of the AMSERV commands that you execute during this sample terminal session 
issue a nonzero return code, for example, 

R (00012); 

you should edit the LISTING file to examine the Access Method Services error 
messages. The publication DOS/VS Messages contains the return codes and reason codes 
issued by Access Method Services? Tou should determine the cause of the error, 
examine the DLBL commands and AMSERV files you used, correct any errors, and retry 
the command. 

#cp define t3330 200 10 
DASD 200 DEFINED 010 CYL 
#cp define t3330 300 10 
DASD 300 DEFINED 010 CYL 
#cp define t3330 400 10 
DASD 400 DEFINED 010 CYL 



These commands define temporary 3330 mindisks at virtual addresses 200, 300, and 
400. 
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File: PUNCH IBCDASDI 

222222 JOB 

MSG TODEV=1052,TOADDR=009 

DADEF TODEV=3330,TOADDR=200,VOLID=SCRATCH,CYLNO=10 

VLD NEWVOLID=222222 

VTOCD STRTADR=10,EXTENT=5 

END 
333333 JOB 

MSG TODEV=1052,TOADBR=009 

DADEF TODEV=3330,TOADDR=300,VOLID=SCRATCH,CYLNO=10 

VLD NEWVOLID=333333 

VTOCD STRTADR=10,EXTENT=5 

END 
4411444 JOB 

MSG TODEV=1052,TOADBR=009 

DADEF TODEV=3330,TOADDR=400,VOLID=SCRATCH,CYLNO=10 

VLD NEWVOLID=444444 

VTOCD STRTADR=10,EXTENT=5 

END 



File: IBCDASDI EXEC 

CP CLOSE C 

CP PURGE RDR ALL 

0003 FILES PURGED 

ACC 190 Z/Z IPL * 

DMSACC724I »190» REPLACES • Z (350) •- DOS 

DMSACC723I Z (190) R/O 

DMSACC725I 190 ALSO = S-DISK 

CP SPOOL D CONT * 

PUNCH IPL IBCDASDI Z ( HOB 

PUMCB 222222 IBCDASDI * ( NOH 

CP SPOOL PUNCH NOCONT 

CP CLOSE PUNCH 

PUN FILE 2753 TO PATTI COPY 01 NOHOLD 

CP IPL 00C 



ibcdasdi 

IBC105A DEFINE INPUT DEVICE. DASDI 7.77 

input=2540,00c 



^p This file contains control statements for the IBCDASDI program, which formats and 
initializes disks for OS and DOS. These disks are labelled 222222, 333333, and 

^^ 444444. Any messages produced by the IBCDASDI program are sent to your terminal. 

^P This file contains the commands necessary to use the IBCDASDI program under CHS. You 
must punch a copy of the IBCDASDI program, followed by the file containing your 
control statements, to your virtual card reader, and then load the IBCDASDI program. 

— ^ This is all done in the file IBCDASDI EXEC. 

^p Execute the IBCDASDI EXEC. The last command in the EXEC is the IPL command, which 
passes control to the IBCDASDI program, which prompts you to enter the address of 

^^ the control statements. 

^P Since the control statements are in your card punch, you indicate the device type 
(2540) and the address (00C) on the INPUT** statement. 
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O DASDI 7.77 

222222 JOB 

MSG TODEV=1052,TOADDR=009 

DADEF TODEV=3330,TOADDR=2 00,VOLID=SCRATCH,CYLNO=10 

VLD NEWVOLID=222222 

VTOCD STRTADR=10,EXTENT=5 

END 
IBC163A END OF JOB. 

DASDI 7.77 
333333 JOB 

MSG TODEV=1052,TOADDR=009 

DADEF TODEV=3330,TOADDR=300,VOLID=SCRATCH,CYLNO=10 

VLD NEWVOLID=333333 

VTOCD STRTADR=10,EXTENT=5 

END 
IBC163A END OF JOB. 

DASDI 7.77 
HUHkHH JOB 

MSG TODEV=1052,TOADER=009 

DADEF TODEV=3330,TOADDR=400,VOLID=SCRATCH,CYLNO=10 

VLD NEWVOLID=4H4444 

VTOCD STRTADR=10,EXTENT=5 

END 
IBC163A END OF JOB. 
DMKDSP450W CF ENTERED; DISABLED WAIT PSW '00060000 0000EEEE' 
ipl cms 
CMS... VERSION 3.0 02/28/76 

if qp link dosres 350 350 ^.i^a^ , 

'^iSjj; i$$h W.EJP Jl/O; R/W BY GANDALF 

'a^i-ss^o^; *■ :',_:* ..,,. .;. ,.. . . ... ., 

DM:s'i:c4 : 7i;ij\zi(350) r/o - bos , .. . 

M&&9&4i!i.XA-*sfiw* . . .... ■ . 



© 



O 

o 

o 



ace e 33^20010 








DMSACC723I B 

R; 

access 300 c 


(200) 


R/W 


- OS 








DMSACC723I C 

R; 

access 400 d 


(300) 


R/W 


- OS 








DMSACC723I D 
R* 


(400) 


R/W 


- OS 


query search 








BBB191 191 


A 


R/W 




222222 200 


B 


R/W - 


OS 


333333 300 


C 


R/W - 


OS 


tmmmn uoo 


D 


R/W - 


OS 


CMS190 190 


S 


R/O 




DOSRES 350 Z 


R/O - 


DOS 



R; 



These messages are issued by the IBCDASDI program, which displays the statements 

executed and indicates the end of each job. 

When the last IBCDASDI job is complete, your virtual machine is in the CP 

environment and you must reload the CMS system before you can continue. 

If you are a CMS/DOS user, you must reaccess the DOS/VS system residence volume and 

issue the SET DOS ON command line, specifying the VSAM option. If you have not 

previously linked to the system residence, you must use the CP LINK command before 

you issue the ACCESS command. 

Access the three newly formatted disks as your B-, C-, and D-disks. 

You can issue the QUERY SEARCH command to verify the status of all disks you 

currently have accessed. 
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File: MASTCAT AMSERV 

DEFINE MASTERCATALCG - 
( NAME (MASTCAT) - 

VOLUME (222222) - 

CYL (4) - 

UPDATEPW (GAZELLE) - 

FILE (IJSYSCT) ) 
assgn syscat b 
E; | 

dlbl ijsysct b dsn mastcat (syscat: perm extent 
DMSDLB331R ENTER EXTENT SPECIFICATIONS: 
19 171 

R; 

amserv mastcat 

R; 



File: CLUSTER AMSERV 

DEFINE CLUSTER ( NAME (BOOK. LIST ) - 
VOLUMES (222222) - 
TRACKS (20) - 
FILE (BOOK) - 
KEYS (14,0) - 
RECORDSIZE (120,132) ) - 
DATA (NAME (BOOK. LIST. DATA) ) - 
INDEX (NAME (BOOK. LIST. INDEX ) ) 

amserv cluster 

4221A ATTEMPT 1 OF 2. ENTER PASSWORD FOR JOB AMSERV FILE MASTCAT 

gazelle 

R; 

File: REPRO AMSERV 

REPRO INFILE (BFILE - 

ENV ( RECORDFORMAT (F) - 
BLOCKSIZE (120) - 
PDEV (3330) ) ) - 
OUTFILE (BOOK) 



The file MASTCAT AMSERV defines the VSAM master catalog that you are going to use. 

Identify the master catalog volume, and use the EXTENT option on the DLBL command so 

that you can enter the extents. For this extent, specify 171 tracks (9 cylinders) 

for the master catalog. Since 4 cylinders are specified in the AMSERV file, the 

remaining 5 cylinders will be used for suballocation by VSAM. 

You must enter a null line to indicate that you have finished entering extent 

information. 

Issue the AMSERV command, specifying the MASTCAT file. The Ready message indicates 

that the master catalog is created. 

Define a suballccated cluster. This cluster is for a key-seguenced data set, named 

BOOK. LIST. 

No DLBL command is necessary when you define a suballocated cluster. Note that 

since the password was not provided in the AMSERV file. Access Method Services 

prompts you to enter the password of the catalog, which is defined as GAZELLE. 

Use the Access Method Services REPRO command to copy a CMS data file into the 

cluster that you just defined. 
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assgn sysOOl a 

R; 

copyfile test data a (recfm f lrecl 120 

R; 

sort test data a book file a 
DMSSRT604R ENTER SORT FIELDS: 
1 14 

R; 

dlbl bfile a cms book file (sysOOl 

R; 

assgn sys002 b 

R; 

dlbl book b dsn book list (vsam sys002 

R; 

amserv repro 

R; 

File: SPACE AMSERV 

DEFINE SPACE - 

( FILE (SPACE) - 
TRACKS (57) - 
VOLUME (333333) ) 

R; 

assgn sys003 c 

R; 

dlbl space c (extent sys003 

DMSDLB331R ENTER EXTENT SPECIFICATIONS: 

19 57 

R; 

amserv space 

4221A ATTEMPT 1 OF 2. ENTER PASSWORD FOR JOB AMSERV FILE MASTCAT 

gazelle 

R; 



lou must identify the d names for the input and output files for the REPRO function. 

BFILE is a CMS file, which must be a fixed-length, 120-character file, and it must 

be sorted alphamerically in columns 1 through 14. The COPYFILE command can copy any 

existing file that you have to the proper record format; the SORT command sorts the 

records on the proper fields. 

The output file is the VSAM cluster, so you must use the VSAM option on this DLBL 

command. 

Create an AMSERV file to define additional space for the master catalog on the 

volume labelled 333333. 

Again, use the EXTENT option on the DLBL command so that you can enter extent 

information, and a null line to indicate that you have finished entering extents. 

Issue the AMSERV command. Again, you are prompted to enter the password of the 

master catalog. 
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@ File: UNIQUE AMSERV 

DEFINE CLUSTER - 

( NAME (UNIQUE. FILE) - 
UNIQUE ) - 

DATA - 

( CYL (3) - 

FILE (KDATA) - 
BECOBDSIZE (100 132) 
KEYS(12,0) - 
VOLUMES (333333 ) ) 

INDEX - 

( CYL (1) - 

FILE (KINDEX) - 
VOLUMES (333333) ) 



© 



dlbl kdata c (extent 

DMSDLB331R ENTER EXTENT SPECIFICATIONS: 

76 57 



RJ 

dlbl kind ex c (extent 

DMSDLB331H ENTER EXTENT SPECIFICATIONS: 

133 19 



R; 

aniserv unique 

4221A ATTEMPT 1 OF 2. ENTER PASSWORD FOR JOB AMSERV 

gazelle 

r; 



FILE MASTCAT 
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File: USERCAT AMSERV 

DEFINE USERCATALOG - 
( CYL (4) - 

FILE (IJSYSUC) - 
NAME (PRIVATE. CATALOG) - 
VOLUME (MHHHH) - 
UPDATEPW (UNICORN) - 
ATTEMPTS (2) ) - 
DATA (CYL (3) ) - 
INDEX ( CYL (1) ) - 
CATALOG (MASTCAT/GAZELLE ) 



- 

dlbl ijsysuc d dsn private catalog (extent 
DMSDLB331R ENTER EXTENT SPECIFICATIONS: 
19 152 



pen 



R; 

amserv usercat 

* 

R; 



This AMSERV file defines a unigue cluster, with data and index components. 

You must enter DLBL commands and extent information for both the data and index 

components of the unigue cluster. 

Next, define a private (user) catalog for the volume 444444. This catalog is named 

PRIVATE. CATALOG and has a password of UNICORN. 

When you define a user catalog that you are going to use as the job catalog for a 

terminal session, you should use the ddnaoe IJSYSUC. 
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TAPE 181 ATTACHED 
File: EXPORT AMSERV 

EXPORT BOOK. LIST - 
INFILE (BOCK) - 
OUTFILE (TEMP ENV (PDEV (2400) 



) ) 
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dlbl 














IJSYSCT 


DISK 


FILE 




IJSYSCT 


B1 


MASTCAT 


BFILE 


DISK 


BOOK 




FILE 


A1 




BOOK 


DISK 


FILE 




BOOK 


B1 


BOCK. LIST 


SPACE 


DISK 


FILE 




SPACE 


C1 




KDATA 


DISK 


FILE 




KDATA 


C1 




KINDEX 


DISK 


FILE 




KINDEX 


C1 




IJSYSUC 

D m 


DISK 


FILE 




IJSYSUC 


D1 


PRIVATE. C 


R; 

dlbl book b dsn 

R; 

amserv texport 


book list 


(cat ijs: 


fsct 


WWW 


(tap out 


181 








DMSAMS361R ENTER TAPE OUTPUT DDHAMES: 




temp 
R; 















@ File: IMPORT AMSERV 

IMPORT - 

CATALOG (PRIVATE .CATALOG/UNICORN) 
INFILE (TEMP ENV (PDEV (2400))) - 
OUTFILE (BOOK2) 

^» tape rev 

R; 

dlbl book2 d dsn book list (vsam ^fy£$04; 

R; 

amserv timport (tapin 181 

DMSAMS361R ENTER TAPE INPUT DDNAMES: 

temp 

R; 



^P You may want to try an EXPORT/IMPORT function, if you can obtain a scratch tape from 
the operator. When the tape is attached to your virtual machine, you receive this 

^^ message. 

K| The file that is being exported is the cluster BOOK. LIST created above. If you do 
not have access to a tape, you can export the file to your CMS A-disk. Remember to 

^-. change the PDEV parameter to reflect the appropriate device type. 

^J Before issuing the AMSERV command to perform the export function, you may want to 
check the DLBL definitions in effect. Issue the DLBL command with no operands to 

€ obtain a list of current DLEL definitions. 
\ you must reissue the DLBL for BOOK. LIST, because there is a job catalog in effect, 
and the file is cataloged in the master catalog. Use the CAT option to override the 
^-. job catalog. 

Q) There is no default tape value when you are using tapes with the AMSERV command. You 
must specify the TAPIN or TAPOUT option and indicate the virtual address of the 
**. tape. You are prompted to enter the ddname, which for this file is TEMP. 
^3 The last AMSERV file imports the cluster BOOK. LIST to the user catalog, 
_^ PRIVATE. CATALOG. 
^P You should rewind the tape before reading it as input. 
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DEFINE 

Access Method Services function 210 
command 

defining a temporary disk 22 
defining virtual storage 227 
to increase virtual storage size 97 
subcommand, defining symbols for a 
debugging session 218 
defining 

logical line editing symbols 18 
program input and output files in CMS 

152 
space for VSAM files 206 

in CMS/DOS 198 
temporary disks 22 
translate tables 40 
virtual printer for trace information 

222 
virtual storage 227 
VSAM files 

for AMSERV 201 

for AMSERV, in CMS/DOS 194 
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operand 

of MACLIB command 146 
of MACLIB command, in CMS/DOS 175 
DELETE 

Access Method Services function 211 
subcommand, how to use 80 
deleting 

lines in a file being edited 80 

to a particular line 80 
members of a MACLIB 
example 146 
example in CMS/DOS 175 
VSAM clusters and catalogs 211 
delimiters, on EDIT subcommand lines 72 
density of tapes, when to specify 131 
DESBOF function 
example 281 

using to clear the console stack 279 
DETACH, command, after RELEASE command 25 
detaching 
disks 25 

without releasing them 65 
device types 

assignments in CMS/DOS 164 
specifying with FILEDEF command 139 
devices, disks, cylinders and tracks 203 
DIAL command 35 

DIRECT, filetype, usage in CHS 55 
DISCONH, command 36 
disconnecting, your terminal from your 

virtual machine 36 
discontiguous, saved systems 228 
DISK 

command 

LOAD operand, restriction in job for 

CMS Batch Facility 236 
using 125 
disk determination 

default for reading files 

commands for which you must specify a 

filemode 61 
commands that search all accessed 

disks 60 
commands that search only the A-disk 

60 
commands that search only the A-disk 
and its extensions 60 
default for writing files 

commands for which you must specify a 

filemode 62 
commands that write files onto your 

A-disk 62 
commands that write output files to a 
read/write disk 62 
filemode selection by the editor 71 
disks 

defined in your VM/370 directory entry 

21 
defining temporary disks for a terminal 

session 22 
definition 21 
DOS, accessing 160 
full, during an editing session 98 
linking 23 
listing information about 49 



master file directory 64 
OS 

determining extents for VSAM 202 
using in CMS 137 
OS and DOS 

formatting with IBCDASDI program 193 
used with VSAM data sets 191 
providing for CMS batch virtual machine 

234 
guerying the status of 64 
read-only, exporting VSAM files from 

211 
search order 24,59 
sharing 23 
VSAM, accessing 191 

writing files on, how the editor selects 
a disk 71 
DISP HOD option, of FILEDEF command 142 
DISPLAY command, displaying storage and 

registers while debugging 223 
display screen, status conditions 326 
display terminals 

changing editor verification setting 

332 
controlling the screen, during edit 

session 332 
display mode 334 

entering backspace characters 335 
entering commands 325 
example of display screen 329 
how the editor formats a screen 331 
line mode 334 
signaling interrupts 329 
using tab characters 335 
using the CMS Editor 330 
displaying 

CMS files 44 

in an EXEC procedure 273 
column numbers in a file being edited, 

using $C0L edit macro 310 
data lines at the terminal 
in an EXEC procedure 272 
HRTERH macro 251 
directories of DOS/VS libraries 171 
DLBL definitions 167 
FILEDEF definitions 152 
general registers, in the debug 

environment 216 
lines at the terminal, in an EXEC 

procedure 113 
listings from Access Hethod Services 

189 
particular columns of a file, during 

edit session 77 
prompting messages in an EXEC procedure 

271 
PSA (Program Status lord) , during 

program execution 220 
screensful of data 333 
short form of editor error message 94 
special characters on a display terminal 

336 
timing information in an EXEC procedure 

115 
trace information on the terminal 222 
virtual storage during program execution 
223 
disposition, of spool files 121 
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command 

assigning filemode numbers 63 
default file definition 167 
defining OS data sets 137 
entering before program execution 

184 
EXTENT option, examples 207 
how to use in CMS/DOS 166 
identifying VSAM data sets 201 
identifying VSAM data sets in CMS/DOS 

194 
relationship to ASSGN command 166 
specifying extents 206 
specifying extents in CMS/DOS 199 
DMS, prefixing error messages in an EXEC 

procedure 293 
documenting, EXEC procedures 291 
DOS (Disk Operating system) 
files 

identifying in DLBL command 167 
restrictions on reading in CMS 162 
using in CMS 160 
macros supported in CMS 176 
program development, summary of commands 

45 
simulation in CMS 159 
DOSLIB 

command, compressing DOSLIBs 182 
files 181 

executing phases from 183 
size considerations 181 
filetype, usage in CMS/DOS 57 
DOSLKED command, link-editing programs in 

CMS/DOS 179 
DOSLNK 

files, using in CMS/DOS 180 
filetype 

usage in CMS/DOS 57 
used by DOSLKED command 180 
DOSMACBO MACLIB 148,176 
DOSPART operand, of CMS SET command, 

example 184 
DOS/VS system residence volume, using in 

CMS/DOS 159 
DSERV command, examples 171 
DSH operand of DLBL command 167 
DSORG option, of FILEDEF command, when to 

specify 141 
DSTRING subcommand 
example 80 

using in edit macros 302 
dummy data set, specifying with FILEDEF 

command 140 
DUMP 

command, example 225 
subcommand, example 225 
dumping, virtual storage 225 
duplicating 

filenames or filetypes 52 
lines in a CMS file 81 
dynamic loading of TXTLIB members 156 
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EDIT command 

creating CMS files 41 
entering edit environment 29 
executing in an EXEC procedure 277 
invoking CMS Editor 69 
edit environment 29 
edit macros 
$C0L 310 
$C0NT 302 
$D00BLE 304 
$DUP 81 
$MACROS 306 
$MARK 307 

entering continuation character in 
column 72 88 
$M0VE 81 
$POINT 309 

CMS commands valid in 298 
distributed with CMS 303 
effect of IMPEX setting 38 
examples 298 
executing 298 
how to write 297 
sample 304 

using variable-length EXEC files 301 
edit mode, returning from input mode 70 
EDIT subcommands 
delimiters 72 

entering on a display terminals 330 
executing in edit macros 300 
stacking in the console stack 277 
summary 99 
editing 

CMS files 69 

lines as you enter them from the 

terminal 16 
on a display terminal 330 
in EXEC procedures 335 
session 69 
end-of-file 

executing edit macros 299 
indicating for input stream to batch 

virtual machine 240 
indicating on jobs sent to batch virtual 

machine 233 
indication in a file being edited 74 
entering 

APL characters on a display terminal 

336 
CMS commands, in CMS subset environment 

29 
CMS environment 28 
CMS/DOS environment 31,159 
commands 13 

more than one command on a line 17 
on display terminals 325 
using synonyms 38 
while a command or program is 
executing 32 
continuation character in column 72 87 
CP commands 

from the CMS command environment 28 
from the edit environment 92 
CP environment 

after a program check 224 
during program execution 33 
from CMS environment 27 
from edit mode 92 
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debug environment 

after program abend 216 
via breakpoint 30,217 
via DEBUG command 30 
via EXTERNAL command 30 
via external interrupt 221 
DEBUG subcommands 30 
DLBL definitions, in an EXEC procedure 

185 
edit environment 29 
EDIT subcommands 72 

on display terminal 330 
extent information when defining VSAH 

master cfatalog 204 
file identifications 
on DLBL command 166 
on FILEDEF command 140 
on LISTDS command 162 
FILEDEF definitions, in an EXEC 

procedure 158 
Immediate commands 32 

on a display terminal 329 
lines at the terminal, during program 

execution 251 
logical line editing symbols as data 18 
multivolume VSAM extents 207 

in CMS/DOS 199 
null lines 13 
special characters 

using a translate table 40 
using the ALTER subcommand 78 
tab characters on a display terminal 

336 
VSAM extent information, in CMS/DOS 196 
entry, linkage, for assembler language 

programs in CMS 242 
ENTRY, OS linkage editor control statement, 

supported by TXTLIB command 153 
entry point 

displayed following FETCH command 182 
for program execution, determining 156 
specifying, using OS ENTRY statement 

153 
specifying for program execution 152 
environments 
VM/370 27 

summary 34 
EOF, token stacked when edit macro executed 

at end-of-file 299 
EOF: message 74 
ERASE, command 43 
erasing 

CMS files 43 

after reading them 63 
to clear disk space during an editing 
session 98 
error messages 

controlling whether you receive them 37 
displayed by the CMS Editor 73 

short form 94 
displaying in red 37 
in an EXEC procedure 292 
errors 

during CMS commands, handling in an EXEC 

procedure 286 
during EXEC processing 292 
handling in an EXEC procedure 287 
in edit macros 300 



ESERV 

command, examples 170 
filetype 170 

usage in CMS/DOS 57 
examining, output listings from Access 

Method Services 189 
EXEC 

built-in functions, summary 111 
command 

using in EXEC procedures 255 
when to use 105 
control statements, summary 116 
files 

changing the record format 104 
differences between fixed-length and 

variable-length 273,278 
record format 104 
stacking 280 
filetype 

for edit macros 297 
usage in CMS 55 
usage in CMS/DOS 57 
interpreter, how lines are processed 

295 
procedures 103 
building 255 
debugging 294 
executable statements 255 
executing from programs 244 
nesting 269 

opening and closing CMS files 249 
setting program function keys 326 
submitting jobs to CMS Batch Facility 

236,237 
testing in CMS subset 294 
to execute DOS programs 185 
to execute IBCDASDI disk 

initialization program 193,361 
to execute OS' programs 157 
used by non-CMS users to submit batch 

jobs 239 
using to submit jobs to CMS Batch 

Facility 232 
with same names as CHS commands 39 
processing errors 292 
special variables, summary 119 
executable statements, in an EXEC procedure 

255 
executing 

Access Method Services, in an EXEC 

procedure 213 
CMS commands 

from programs 243 
in edit macros 298 
in EXEC procedures 285 
CMS EXECs 107 
commands, using program function keys 

325 
CF commands 

from programs 244 
in an EXEC procedure 255 
DOS programs 

sample terminal session 355 
setting the UPSI byte 184 
specifying a virtual partition size 

184 
using EXEC procedures 185 
DOS/VS procedures 170 
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edit macros 298 

verifying completion 301 
EDIT subcommands 

in an EXEC procedure 277 
using program function keys 326 
EXEC procedures 65,103,104 
from programs 244 

in jobs for CMS Batch Facility 236 
executable statements in an EXEC 

procedure 255 
Immediate commands, in an EXEC procedure 

274 
MODULE files 66, 157 

from programs 244 
OS programs 152 

restrictions 151 
using EXEC procedures 157 
PROFILE EXEC 105 
programs 

in CMS/DOS 182 
sample terminal session 351 
TEXT files 152 
VSAH programs 187 
execution 

conditional, using the SIF control 

statement 263 
paths in an EXEC procedure 262 
execution summary of an EXEC 
description 115 

example when SCONTROL ALL is in effect 
294 
exit linkage, for assembler language 

programs in CMS 242 
exiting 

from an EXEC procedure 111,269 

based on 8RETC0DE special variable 
287 
EXPORT, Access Method Services function 

211 
exporting, VSAM data sets 211 
extensions, read-only, using 59 
EXTENT option 

of DLBL command 202 
in CMS/DOS 194 
extents 

determining for VSAM functions 192 
for VSAM files 

entering in CMS/DOS 196 
multiple 207 
multiple in CMS/DOS 199 
EXTERNAL, command, interrupting program 

execution 221 
external references, how CHS loader 

resolves 154 
extracting, members of MACLIBs 147,176 



FETCH command, executing programs in 

CMS/DOS 182 
fetching, core image phases for execution 

in CHS/DOS 182 
FIFO, first-in first-out stacking, in an 

EXEC procedure 276 
file 

definitions, making with FILEDEF command 
139 



directories, CHS 64 

format, specifying on FILEDEF command 

141 
identifier 

assigned by FILEDEF command 140 
changing with the SAVE subcommand 92 
CHS, rules for assigning 51 
coded as an asterisk (*) 52 
coded as an equal sign (=) 53 
default assigned by DLBL command 167 
specifying for an FSCB 245 
used in FSCB 246 
size, relationship to record length 83 
system 51 

macro instructions 245 
FILE subcommand, writing a file onto disk 

71 
FILEDEF 
command 

assigning filemode numbers 6 3 

default definition 140 

guidelines for entering 139 

how to use 139 

used to identify OS macro libraries 

148 
used with OS data sets 137 
commands, issued by the assembler, 
overriding 179 
filemode 

in file identifier 51 
letters 52 

assigning 58 

when to specify, reading files 60 
when to specify, writing files 61 
numbers 

descriptions 62 
when to specify 63 
4 138 
filename 51 

for edit macros 297 
files (see also DOS files, OS data sets) 
CHS 

erasing 43 
format 51 
identifiers 51 

identifying on DLBL command 167 
maximum number of records 51 
renaming 42 

too large to edit, what to do 97 
manipulating with CHS macro instructions 

245 
that are erased after they are read 63 
filetype 

created by assembler and language 

processors 56 
for workfiles 58 
in file identifiers 51 
reserved 53 

establishing your own 289 
used by CHS commands 54 
used by language processors 54 
FIND, subcommand, how to use 74 
first-in first-out stacking, in an EXEC 

procedure 276 
fixed-length, EXEC files, difference 

between 6STACK and &BEGSTACK 278 
fixed-length files, converting to 
variable-length 83 
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FMODE 

subcommand 

examples 93 

used to change filemode numbers 63 
FOR, operand of SPOOL command, usage 122 
FORMAT command, formatting a CHS disk 22 
format of disk files, specifying on FILEDEF 

command 141 
formatting 

CHS disks, example 22 

OS and DOS disks, example 193 
forming, tokens of words in an EXEC 

procedure 255 
free space on OS and DOS disks, determining 

for use with VSAM 192 
FSCB, macro, usage 245 
FSCB (file system control block) 

creating 245 

fields defined 246 

modifying for read/write operations 247 

usage 245 

using with I/O macros 247 
FSCBD macro, generating a DSECT for an FSCB 

247 
FSCLOSE macro, example 249 
FSERASE macro, usage 249 
FSREAD macro, examples 247 
FSWRITE macro, examples 247 
full disk 64 

during an editing session 98 



GEN operand 

of HACLZB command 
usage 145 

usage in CMS/DOS 173 
general registers 

conventions used in CMS 241 
displaying in debug environment. 216 
displaying with the DISPLAY command 223 
modifying during program execution 216 
GENHOD command 

creating a user-written CMS command 157 
regenerating existing MODULES 225 
GETFILE subcommand 
how to use 80 

used to create small files from a big 
one 98 
global changes, using EDIT subcommands 79 
GLOBAL command 

used to identify DOSLIBs 181 

used to identify macro libraries 144 

in CMS/DOS 172 
used to identify OS macro libraries 

137,148 
used to identify TXTLIBs 153 
GO subcommand, to resume program execution 
217 



H 

halting 

program execution 32 
screen displays 330 . 
terminal displays 32 

in an EXEC procedure 274 



hexadecimal, conversion in an EXEC 

procedure 258 
HOLD, operand of SPOOL command 122 
hold status, placing virtual output devices 

in during debugging 215 
holding 

display on a display terminal 327 
spool files to keep them from being 
processed 122 
HOLDING status, on a display screen 327 
HT Immediate command 32 

executing in an EXEC procedure 274 
HX 

DEBUG subcommand 217 
Immediate command 32 

effect in CMS subset 30 
effect on DLBL definitions 167 
effect on FILEDEF definitions 142 



IBCDASDI disk initialization program 
formatting temporary disks 
example 193,361 
ID card, to submit jobs to CMS Batch 

Facility 231 
identifying 

macro libraries to search 144 

in CMS/DOS 172 
multivolume VSAM files 208 

in CMS/DOS 199 
VSAM master catalog 203 
VSAM master catalog in CMS/DOS 195 
IEBPTPCH utility program, creating CMS 

files from tapes created by 130 
IEBUPDTE utility program, creating CMS 

files from tapes created by 130 
IEHMOVE utility program, creating CMS files 

from tapes created by 131 
IJSYSCL, defining in CMS/DOS 166 
IJSYSCT 

defining 203 
defining in CMS/DOS 195 
IJSYSRL, defining in CMS/DOS 166 
IJSYSSL, defining in CMS/DOS 166 
IJSYSUC 

defining 205 
defining in CMS/DOS 197 
image setting, effect on tab characters 84 
IMAGE subcommand, using in edit macros 302 
Immediate commands 

entering, on a display terminal 329 
summary 313 
IMPCP operand, of CHS SET command, setting 

28 
implied 

CP function 28 

controlling 38 
EXEC function 105 
controlling 38 
IMPORT, Access Hethod Services function 

211 
importing, VSAM data sets 211 
INCLUDE 

command, entering after LOAD command 

154 
DOS/VS linkage editor control statement, 
specifying in DOSLNK file 180 
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increasing, virtual machine storage 97 
INPUT 

operand, of CMS SET command, defining an 

input translate table 40 
subcommand 

inserting a single line into a file 

80 
stacking in an EXEC procedure 278 
using in edit macros 301 
input and output files, VSAH, defining 201 
input data 

left margin while using the editor 85 
right margin while using the editor 87 
translated to uppercase by the editor 
70 
input mode 29,70 

entered after REPLACE subcommand 80 
on a display terminal 330 
on a display terminal in line mode 334 
returning to edit mode, in an edit macro 
302 
input stack, clearing 279 
inserting 

lines in a file being edited 80 
using line-number editing 90 
instructions 

calculating virtual storage address 216 
tracing 221 
Interactive Problem Control System (see 

IPCS (Interactive Problem Control System)) 
interrupting 

execution of edit macros 300 
program execution 31 

with a breakpoint 217 
interrupts 

CMS macros for handling 252 
external 221 

signaling on a display terminal 329 
invoking 

Access Method Services 188 
CMS Editor 69 
EXEC procedures 104 
VSAPL on a display terminal 336 
I/O 

device assignments in CMS/DOS 164 

manipulating 165 
macros used in CMS programs 245 
IPCS (Interactive Problem Control System) 

13 
IPL command 

to enter CMS environment 28 
using to load CMS 16 
ISAM access method 

CMS restriction 138 
CMS/DOS restriction 162 



job catalog 
using 205 

using in CMS/DOS 197 
job control language, eguivalent in CMS 

136 
JOBCAT, CMS eguivalent 136 
jobname 

for job sent to CMS Batch Facility 
specifying 233 
used to identify spool files 236 



jobs, for CMS Batch Facility, submitting 
231 



L 
labels 

DOS VSAM disks, determining for AMSERV 

195 
in an EXEC procedure 

how SGOTO searches for 265 
rules for forming 262 
in EXEC procedures 111 

terminating a loop 268 
OS VSAH disks, determining for AMSERV 

204 
tape 129 

using VSAM tapes 209 
using VSAM tapes in CMS/DOS 201 
writing on CMS disks 22 
large files, splitting into smaller files 

97 
LDRTBLS operand, of CMS SET command, usage 

227 
leaving 

CMS subset environment 30 
CMS/DOS environment 31 
debug environment 30,217 
edit environment 30,71 
input mode 70 
length, of lines displayed at your 

terminal, controlling 37 
libraries 

CMS (see also DOSLIB, MACLIB, TXTLIB) 
144 

distributed with the CMS system 

148,176 
macro libraries (see macro 

libraries, CMS) 
TEXT libraries 153 
DOS/VS 

identifying in CMS/DOS 166 
using directories 171 
using in CMS/DOS 168 
DOS/VS core image, executing phases from 

183 
DOS/VS procedure, copying procedures 

169 
DOS/VS relocatable 

copying modules from 169 
link-editing modules from 180 
DOS/VS source statement, using in CMS 

168 
OS, using in CMS 148 
LIFO 

last-in first-out stacking 
in an EXEC procedure 276 
in edit macros 299 
line 

mode, of the CMS Editor 334 
pointer (see current line pointer) 
LIMEDIT macro, executing CP commands 244 
LINEMODE subcommand, beginning line-number 

editing 89 
line-number editing 89 

sample terminal session 348 
lines, deleting at the terminal before 
entering 17 
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LINK command 

format in job for batch facility 235 
linking to other user's disks 23 
linkage conventions, for programs executing 

in CHS 242 
linkage editor 
DOS/VS 

invoking in CMS/DOS 179 
specifying control statements 180 
maps, using when debugging 215 
OS, control statements supported by 
TXTLIB command 153 
link-editing 

modules from DOS/VS relocatable 

libraries 180 
programs in CMS/DOS 179 

specifying linkage editor control 
statements 180 
TEXT files and TXTLIB members 154 
TEXT files in CMS/DOS 180 
examples 180 
linking 

to other users' disks 23 
to your own disks 23 
LISTCAT, Access Method Services function, 

output 189 
LISTCRA, Access Method Services function, 

output 189 
LISTDS command 

listing DOS files 162 

listing extents occupied by VSAM files 

191 
listing free space exents 191 
used with OS data sets 137 
LISTING, assembler ddname, overriding 

default definition 151 
listing 

edit macros, with $MACR0S edit macro 

306 
information 

about CMS files 48,107 
about disks 49 
about DOS files 161 
about MACLIB members 147,175 
about OS and DOS disks 191 
about OS and DOS files 49 
about your terminal 47 
about your virtual machine 50 
logical unit assignments in CMS/DOS 165 
listing files 

created by AMSERV command 

changing the filename 190 
printing 190 
created by assembler and language 

processors 56 
created by ESERV command 170 
created by the assembler, output 
filemode 149 
LISTING filetype 

created by AMSERV command 189 
usage in CMS 55 
usage in CMS/DOS 57 
LISTIO command, listing device assignments 

165 
literal values, using in an EXEC 257 
LKEDIT filetype, usage in CMS 55 
LOAD, command, loading and executing TEXT 
files 152 



load map 

produced by LOAD and INCLUDE commands 

155 
using when debugging 215 
LOAD MAP file, created by CMS loader 155 
loader 
CMS 

description 154 
entry point determination 156 
control statements, summary 155 
tables 

effect of LOAD and INCLDDE commands 

154 
usage 227 
Loader Terminate (LDT) loader control 

statement, usage 153 
loading 

CMS into your virtual machine 16 
specifying virtual device address 
228 
core image phases into storage for 
execution 182 
programs into storage, specifying 

storage locations 244 
TEXT files into storage 152 
TXTLIB members 

dynamically 156 
into storage 153 
LOADLIB filetype, usage in CMS 55 , 
LOADMOD command, to debug a MODULE file 

225 
LOCATE subcommand 
how to use 74 
using in edit macros 302 
locating 

lines in a file being edited 74 
using line-number editing 90 
location, starting, for loading link-edited 

phases 182 
locking, terminal keyboard to wait for 
communication 39 
logging off VM/370 36 
logging on to VM/370 15,35 
logical 

character delete symbol 16 
escape symbol 18 
line delete symbol 17 
line editing symbols 16 
defining 18 
overriding 38 
used with the editor 70 
line end symbol (see also # logical 

line end symbol) 17 
operators, used for comparisons in EXEC 

procedures 113 
record length of a CMS file, overriding 

editor defaults 81 
units, assigning in CMS/DOS 164 
LOGOFF command 36 
LOGON command 35 

contacting VM/370 15 
LONG, subcommand, when to use 94 
loop, during program execution, debugging 

220 
looping 

in an EXEC procedure 112 

based on number of arguments passed 
260 
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using counters 266 
using the SLOOP control statement 
266 
lowercase letters 

suppressing translation to uppercase 84 
translated to uppercase by the editor 
70 
LEECL option 

of COPYFILE command, truncating records 

in a file 82 
of EDIT command, when to use 81 
of FILEDEF command, when to specify 141 



M 
MACLIB 

command 

usage 145 

usage in CMS/DOS 172 
files 

adding MACRO files created by ESERV 

program 170 
querying 145 
querying, in CMS/DOS 172 
filetype, usage in CHS 55 
MACRO 
files 

adding to MACLIB 146 
adding to MACLIB in CMS/DOS 174 
created by ESERV command 170 
filetype 

usage in CMS 55 
usage in CMS/DOS 57 
macro libraries 
CMS 144 

adding to 146 
creating 145 
deleting members of 146 
displaying information about members 
in 147 
distributed with the CMS system 

148,176 
replacing members of 146 
using in CMS/DOS 172 
DOS/VS assembler language, restriction 

on using in CMS/DOS 172 
OS, identifying for use in CMS 148 
macros 

DOS/VS assembler language 

creating a CMS MACLIB 355 
supported in CMS 176 
OS, supported in CMS 149 
MAP 

filetype 

created by DOSLKED command 182 
created by DSERV command 171 
created by MACLIB command 147,175 
usage in CMS 55 
usage in CMS/DOS 57 
written to A-disk 62 
operand 

of MACLIB command 147,175 
option of DOS/VS ACTION control 
statement, effect in CMS/DOS 182 
maps 

created by DOS/VS linkage editor 182 
of CMS virtual storage 228 



margins 

setting left margin for input with the 

editor 85 
setting right margin for input with the 
editor 87 
master catalogs 
VSAM 

defining 204 
defining in CMS/DOS 196 
master file directory 64 
maximum, number of records in a CMS file 

51 
MEMBER option 

CMS commands that have a MEMBER option 

175 
of FILEDEF command 142 

to copy a member of an OS partitioned 
data set 143 
MEMO filetype 58 
MESSAGE command, using before logging on 

35 
messages 

controlling whether you receive them 36 

from CMS Batch Facility 234 

from CP during edit session, effect on 

display screen 332 
from the editor, on a display terminal 

330 
sending to other virtual machine users 
35 
minidisks (see also disks) 
definition 21 
transporting to OS system after using 

with CMS VSAM 191 
using with VSAM data sets 191 
EXPORT/IMPORT restriction 211 
mode 

edit and input 70 
setting for your terminal 31,39 
switching 27 
summary 34 
modifying 

CMS EXECs 108 

CHS files, examples of commands 42 
FSCB 247 

groups of CMS files 61 
registers during program execution 216 
MODULE 
files 

creating 157 

debugging 225 

executing from programs 244 

generating, to execute in transient 

area 245 
modifying 225 
filetype, usage in CMS 56 
modules, DOS/VS relocatable, copying into 

CMS files 169 
MORE... status, on a display screen 327 
MOVEFILE command 

copying OS data sets 142 

copying tape files 130 

reading files from virtual card reader 

126 
to extract a member of a MACLIB 147,176 
used with OS data sets 137 
moving 

CMS files, examples of commands 43 
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current line pointer 73 
lines in a file being edited 81 
MULT option of DLBL command 202 

in CMS/DOS 194 
multiple 

extents for VSAM files 
specifying 206 
specifying in CMS/DOS 199 
output devices, restriction in CMS/DOS 

166 
variable symbols in a token, examples 
257 
multivolume VSAM extents 
specifying 207 
specifying in CMS/DOS 199 



NAME, OS linkage editor control statement, 

supported by TXTLIB command 153 
naming, CMS files 51 
nesting 

GIF statements in an EXEC procedure 264 
EXEC procedures 269 

return code passed 287 
nnnnn subcommand, examples 90 
NODISP option of EDIT command, using in 

EXEC procedures 335 
nonrelocatable modules, creating 157 
nonshared copy 
of CMS 228 

of saved system, obtaining during 
debugging 229 
UOPROF option, of ACCESS command, 

suppressing execution of PROFILE EXEC 106 
NOT ACCEPTED status, on a display screen 

327 
nucleus-resident CMS commands 66 
null 
line 

after IPL 16 

at top of file 74 

entering to determine environment 27 

how to enter 13 

in an EXEC procedure 255 

stacking in an EXEC 213,278 

testing for in an EXEC procedure 271 

to resume program execution after 

attention interrupt 32 
to return to edit mode from input 
mode 70 
variables in an EXEC 110 



object files 

created by assembler and language 
processors 56 

loading into storage 152 
opening, CMS files 249 
options, for FILEDEF command 141 
ORDER command, selecting files for 

processing 124 
origin, for debug environment, setting 218 
ORIGIN, subcommand, how to use 218 



OS 

access methods supported in CMS 138 
data sets 

copying into CMS files 142 
restrictions on reading in CMS 138 
using in CMS 137 
disks, using in CMS 137 
linkage editor control statements , read 

by TXTLIB command 153 
macros supported in CMS 149 
partitioned data sets (see partitioned 

data sets) 
program development 

sample terminal session 351 
summary of commands 44 
simulated data sets 138 
simulation in CMS 135 
utility programs, creating CMS files 
from tapes created by 130 
OSMACRO MACLIB 148,176 
0SMACR01 MACLIB 148,176 
output 

files, produced by ASSEMBLE command 179 
from CMS Batch Facility 236 
from virtual console, spooling 328 
OUTPUT, operand, of CMS SET command, 

defining an output translate table 40 
output stack, clearing 279 
OVERLAY subcommand 
how to use 78 

overlay more than one line 79 
using in edit macros 302 
overlaying 

character strings 78 

with $MARK edit macro 307 
virtual storage, during program 
execution 244 
overriding, logical record length of a file 
being edited 81 



parameter lists 

passing with START command 152,243 
setting up to execute a CMS command 243 
used by CMS routines 242 
using FSCB 246 
parent disk, of read-only extension 59 
parentheses, scanned by EXEC interpreter 

255 
partition size, specifying for program 

execution, in CMS/DOS 184 
partitioned data sets 

copying into CMS files 143 
specifying member names with the FILEDEF 
command 142 
passing 

arguments 

to an EXEC procedure 258 
to nested EXEC procedures 269 
control in an EXEC procedure 264,266 
passwords 

entering on LOGON command line 35 
for VSAM catalogs 206 

in CMS/DOS 198 
for your virtual machine 15 
supplying on LINK command line 23 
PA1 key, to enter CP environment 329 
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PDS option, of MOVEFILE command, to copy OS 

partitioned data sets 143 
periods, used to concatenate EXEC variable 

symbols 110 
PERM option, of FILEDEF command, when to 

specify 141 
PF keys (see program function keys) 
phases, CMS/DOS core image, writing into 

DOSLIBs 181 
positioning 

current line pointer 73,76 

using $P0INT edit macro 309 
tapes, examples 128 
preparing, jobs for CMS Batch Facility 234 
PRESERVE subcommand 

saving EDIT subcommand settings 94 
using in edit macros 301 
preserving, editor settings 94 
PRINT 

Access Method Services function, output 

189 
command, printing CMS files 43 
printer files 

produced by job running in batch virtual 

machine 235 
querying the status of 123 
printing 

Access Method Services listings 189 
CMS files 43 
multiple copies 122 
trace information on virtual printer 
222 
PRINTL macro, usage 251 
privilege classes, for CP commands 319 
PROC filetype 169 

usage in CMS/DOS 57 
procedures, DOS/VS, copying into CMS files 

169 
PROFILE EXEC 
sample 105 

for OS VSAM user 204 
sample for CMS/DOS VSAM user 195 
program 

abend, message 215 

check, using CP to debug 224 

debugging 215 

dumps, obtaining 225 

execution 

entry point determination 156 
interrupting 31 

resuming with BEGIN command 225 
tracing 220 
input and output files, identifying 139 
interrupts 

address stops 33 
breakpoints 33 
libraries 153 
linkage, in CMS 241 
listings, using when debugging 215 
loops, debugging 220 
program development 
DOS programs 159 

sample terminal session 355 
summary of commands 45 
OS programs 135 

sample terminal session 351 
summary of commands 44 
using CMS 133 



program function keys 
setting 325 

COPY function 328 
for EDIT subcommands 334 
in EXEC procedures 326 
logical tab stops 335 
using 325 
Program Status Word (see PSH (Program 

Status Word)) 
programmer logical units, assigning in 

CMS/DOS 165 
prompting 

for line numbers while line-number 

editing 90 
messages in an EXEC procedure 271 
protecting, files from being accessed 62 
PSERV command, examples 169 
PSW, operand of DISPLAY command 220 
PSW (Program Status Word) 
displaying 

in debug environment 216 
while program loops 220 
with DISPLAY command 224 
modifying wait bit 224 
PUNCH 

command 

example 125 

punching jobs to batch virtual 

machine 232 
using with &PUNCH control statement 
283 
ESERV control statement, executing in 
CMS/DOS 170 
punch files, produced by job running in 

batch virtual machine 235 
PUNCHC macro, usage 251 
punching 

CMS files 43 

files to your virtual card punch 125 

jobs to the batch virtual machine 232 

in EXEC procedures 237 
lines in an EXEC procedure 114 
lines to the virtual card punch 126 
members of HSCLIBs 147,176 
PURGE, command, purging spool files 124 



QSAM access method, CMS support 138 
QUERY 

command (CMS) , used with OS data sets 

137 
command (CP) , displaying the status of 
spool files 123 
QUIT subcommand, terminating an edit 
session 71 



RDTERM macro, examples 251 

read, to virtual console, definition 31 

READ control card, punching 125 

READCARD command 
examples 125 

restriction in CMS Batch Facility 236 
used to assign filemode numbers 63 
using with &PUNCH control statement 282 
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READER operand 

of ASSGN command, restriction in job for 

CMS Batch Facility 236 
of FILEDEF command, restriction in job 
for CMS Batch Facility 236 
reading 

arguments from terminal during EXEC 

processing 263 
cards from your virtual card reader 124 
CMS commands 

from the console stack 277 
from the terminal during EXEC 
processing 271 
CMS files 

from an EXEC procedure 280 
from the console stack 280 
with the FSREAD macro 248 
DOS files in CMS 162 
files from tapes 127 
from the terminal 

in an EXEC procedure 113 
RDTERM macro 251 
lines from the console stack, in an EXEC 

procedure 275 
real card decks into your virtual 

machine 125 
specific records in a CMS file 248 
variable symbols from the terminal 
during EXEC processing 271 
read-only, extensions, using 59 
read/write 

pointer, positioning 249 
status of disks 
displaying 24 

in VM/370 directory entry 21 
Ready message 18 

controlling how it is displayed 37 
CPU times displayed 241 
displaying return code from EXEC 

procedures 270 
not displayed after #CP function used in 
CMS environment 29 
RECFM, option, of FILEDEF command, when to 

specify 141 
record format 

describing for file being edited 81 
of a CMS file, changing 83 
specifying for DOS files 163 
specifying for program input and output 
files 141 
record length 

creating long records with the editor 

82 
of a CMS file 
changing 82 

default values set by the editor 81 
relationship to file size 83 
records, in a CMS file, maximum number 51 
recursion level of EXEC, testing with 

SGLOBAL special variable 269 
red type, displaying error messages in 37 
re-entering, EDIT subcommands 95 
re-executing, EDIT subcommands 95 
register 15 

checking contents after program 
execution 158 
in CMS/DOS 186 



register 15 (cont.) 

contents after CMS command execution 

242 
testing contents in an EXEC procedure 
287 
registers (see general registers) 
relative record number, specified in FSCB 

246 
RELEASE command 24 

updating master file directory 64 
used with OS disks 137 
releasing 

disks 24,64 

read-only extensions 60 
relocatable 

modules, link-editing in CMS/DOS 180 
object files, loading into storage for 
execution 154 
Remote spooling communications Subsystem 
(s§e RSCS (Remote Spooling Communications 
Subsystem (RSCS)) 
remote terminals, using the CMS Editor 334 
RENAME command, renaming CMS files 42 
renaming, CMS files 42 
RENDM subcommand, usage 91 
renumbering, records in a file, while 

line-number editing 91 
REP 

operand 

of MACLIB command 146 
of MACLIB command in CMS/DOS 174 
REPEAT subcommand, used with OVERLAY 

subcommand 79 
REPLACE 

option of COPYFILE command, used to 

change filemode letters 63 
subcommand 

how to use 80 
using in edit macros 301 
replacing 

lines in a file being edited 80 
using line-number editing 90 
members in a macro library, example in 
CMS/DOS 174 
REPRO, Access Method Services function 211 
resolving, unresolved references 154 
responding 

to CMS commands in an EXEC procedure 

115 
to prompting messages from AMSERV, in an 
EXEC procedure 213 
responses 

from CMS commands 19 

suppressing the display in an EXEC 
procedure 274 
from CP commands 19 
from VM/370 18 

to CMS commands, stacking in an EXEC 
procedure 275 
RESTORE 

subcommand 
usage 95 

using in edit macros 301 
restoring 

editor settings 95 
screen display during edit session, 
using TYPE subcommand 332 
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restrictions 

on commands used in CHS Batch Facility 

235 
on ddnames in OS VSAH programs 201 
on executing DOS programs in CMS/DOS 

182 
on executing OS programs in CMS 151 
on executing OS programs in CMS/DOS 160 
on number of lines that can be stacked 

in an edit macro 300 
on programs executing in transient area 

245 
on reading DOS files in CMS 162 
on reading OS data sets in CMS 138 
on using DOS/VS macro libraries in 

CMS/DOS 172 
on using minidisks with VSAM data sets 
191 
resume 

program execution 

after a program check 216 
after an attention interrupt 32 
terminal displays 32 

in an EXEC procedure 274 
RETURN 

CHS subset command, to leave CMS subset 

3 
DEBUG subcommand, before starting 
program execution 217 
return codes 

displayed in Ready message 242 
from Access Method services 189 
from an EXEC procedure 270 
from CMS commands 

displaying during EXEC processing 

285 
specifying error address following 
SVC 202 243 
in CMS Ready message 19 
passed by register 15 242 
1 285 
-2 300 
-3 285 
REUSE subcommand 

after LOCATE or FIND subcommand 75 
usage 95 
RSCS {[Remote spooling Communications 
Subsystem) 13 

general information 131 
RSERV command, examples 169 
RT Immediate command 32 

executing in an EXEC procedure 274 
RUN, command, specifying arguments 243 
RUNNING status, on a display screen 327 



SAM files (see sequential access method 
(SAH) files) 

sample, terminal sessions 339 

SAVE subcommand 

changing file identifier 92 
writing a file onto disk 70 

scanning 

CHS command lines 242 

lines in an EXEC procedure 255,295 

tokens in an EXEC procedure 108 



screen 

example of 3270 screen display 329 
format used by the CHS Editor 331 
status 

CP READ 326 
HOLDING 327 
HORE... 327 
NOT ACCEPTED 327 
RUNNING 327 
VH READ 326 
SCRIPT 

command, restriction on executing in 

CMS/DOS 160 
files 58 

using backspaces 86 
filetype, usage in CMS 56 
SCROLL subcommand, how to use 333 
search order 

for CMS commands, summary 67 

for executable phases in CMS/DOS 183 

of CHS commands, considerations when 

naming EXEC procedures 288 
of CHS disks 59 

displaying 24 
used by DOSLKED command 180 
searching 

disks for CHS files (see disk 

determination) 
for a line in a file being edited 74 
for label in an EXEC procedure 265 
only particular columns of a file being 

edited 77 
read-only extensions 59 
segment, shared system loaded into 229 
sending messages, to other virtual machine 

users 35 
sequence numbers, specifying identifier 88 
sequential access method (SAH) files, 

reading in CHS/DOS 162 
serial numbers 

changing verification setting to display 

89 
in a file being edited 88 
SERIAL subcommand, examples 88 
serializing 

records in a file 88 

while line-number editing 90 
SET command (CHS) 

controlling message displays 37 
operands invalid in job for CHS Batch 

Facility 236 
setting implied CP and EXEC functions 
38 
SET command (CP) , controlling message 

displays 36 
SETSSI, OS linkage editor control 
statement, supported by TXTLIB command 
154 
setting 

entry point for program execution 156 
limits on system resources during batch 
jobs 233 
program function keys 325 
in edit macros 326 
sharing 

CHS system 228 
virtual disks 23 
SHORT subcommand, when to use 94 
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simulated data sets 

filemode number of 4 63 
format 138 
size 

of a CMS file 
maximum 51 

relationship to record length 83 
of virtual storage in your virtual 
machine 227 
skipping, lines in an EXEC procedure 266 
SLEEP command 

locking terminal keyboard 39 
using on display terminals 327 
sorting 

CMS EXEC 107 

directories of DOS/VS libraries 171 
special variables, EXEC (see EXEC special 

variables) 
specifying 

device type for FILEDEF command 139 
filemode numbers, on DLBL and FILEDEF 

command 63 
which records to read or write 248 
splitting, CMS files into smaller files 97 
SPOOL command 

changing characteristics of unit record 

devices 121 
spooling console output 328 
spool file, determining the status of 123 
spool files 121 

controlling in job for CMS Batch 

Facility 235 
determining the status of 50 
produced by CMS Batch Facility, 
controlling 236 
spooling 

basic description 121 
console output 328 
multiple copies 122 
SSERV command, examples 168 
STACK, subcommand, using in edit macros 

303 
stacking 

CMS commands, in an EXEC procedure 277 
command lines, after attention interrupt 

32 
commands lines, with # (logical line end 

symbol) 17 
EDIT subcommands 277 
in edit macros 297 
with REUSE subcommand 95 
EXEC files in the console stack 280 
Immediate commands in an EXEC procedure 

274 
last-in first-out in an EXEC procedure 

276 
lines in an EXEC procedure 115 

limitations 275,300 
lines in the console stack, in an EXEC 

procedure 275 
null lines 

after attention interrupt 32 
in EXEC procedures 213,278 
responses in EXEC procedures 275 
AMSERV command 213 
DLBL command 185 
FILEDEF command 158 
to CMS commands 115 



START 

command 

after LOAD command 152 
used with FETCH command 182 
option 

of FETCH command 182 
of LOAD command 152 
starting, program execution in CMS 152 
STATE command, used with OS data sets 137 
STEPCAT, CMS eguivalent 136 
STORE 

CP command, using to change the Program 

Status Word (PSW) 220 
subcommand, changing storage locations 
218 
suballocated VSAM cluster, defining 210 
submitting 

jobs to CMS Batch Facility 231 
non-CMS users 239 
substituting, variable symbols in an EXEC 

procedure 256 
summary 

of CMS commands 314 
of CMS/DOS commands 161 
of CP command privilege classes 319 
of CP commands 320 
of DEBUG subcommands 219 
of EDIT subcommands 99 
of EXEC built-in functions 111 
of EXEC control statements 116 
of EXEC special variables 119 
of Immediate commands 313 
suppressing 

long form of editor 7EDIT message 94 
verification of changes made by the 
editor 94 
SVC 

instructions 

tracing with CP TRACE command 222 
tracing with SVCTRACE command 223 
SVC 202, used to call a CMS command 243 
SVCTRACE command, usage 223 
symbolic addresses for tapes 126 
symbols 
debug 

defining 218 

using with DEBUG subcommands 218 
logical line editing 16 
used for comparisons in EXEC procedures 

113 
variable, in an EXEC procedure (see 
variable symbols) 
SYNONYM 

command, invoking synonym tables 38 
filetype, usage in CMS 56 
synonyms, for CMS and user-written 

commands, defining 38 
SYSCAT, assigning in CMS/DOS 195 
SYSCLB 

assigning in CMS/DOS 164 
unassigning 183 
SYSIN 

assigning in CMS/DOS 164 
input for ESERV command 170 
SYSIPT, assigning in CMS/DOS 164 
SYSLIB, ddname used to identify OS macro 

libraries 149 
SYSLOG, assigning in CMS/DOS 164 
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SYSLST 

assigning in CMS/DOS 164 
output from ESERV program 170 

SYSPCH 

assigning in CMS/DOS 164 
output from ESERV program 170 

SYSRDR, assigning in CHS/DOS 164 

SYSRLB, assigning in CMS/DOS 164 

SYSSLB, assigning in CMS/DOS 164 

system disk, files available 62 

system logical units 164 

SYSUT1 filetype 58 

SYSUT2 filetype 58 

SYSUT3 filetype 58 

SYS0T4 filetype 58 

SYSXXX 

option of DLBL command 166 

programmer logical units, assigning 164 

SYS001 filetype 58 

SYS002 filetype 58 

SYS003 filetype 58 

SYS004 filetype 58 

SYS005 filetype 58 

SYS006 filetype 58 



T 
tab 

characters 

deleted in user input area 336 
entering in a file being edited 84 
using in edit macros 302 
using on display terminals 335 
settings, used by the editor 85 
TABSET subcommand, using in edit macros 

302 
TAPE command, examples 128 
tapes 

considerations for CMS/DOS users 163 

controlling 126 

density of, when to specify 131 

for AMSERV, example 212 

labels 129 

processing in CMS 163 
reading 209 
reading in CMS/DOS 201 
used for AMSERV input and output 208 
in CMS/DOS 200 
TAPn, symbolic addresses for tapes 126 
TAPPDS command, copying files from tapes 

130 
temporary disks, using for VSAM data sets 

193 
TERMINAL, command, setting logical line 

editing symbols 18 
terminals 

characteristics, setting 37 

commands to control communications 35 

communication in an EXEC procedure 271 

disconnecting 36 

display (see display terminals) 

input buffer (see console stack) 

macros for communication 251 

mode setting 31,39 

display terminals 327 
sample sessions 339 
terms, OS, eguivalents in CMS 136 



testing 

arguments passed to an EXEC procedure 
260 
EXEC procedures, using CMS subset 294 
for a null line entered in an EXEC 271 
return codes from CMS commands 270 

in an EXEC procedure 271 
variables symbols, using the &IF control 
statement 263 
TEXT 

assembler output ddname, overriding 
default definition 151 
files 

created by assembler and language 

processors 56 
link-editing in CMS/DOS 180 
loading into storage 153 
filetype 

usage in CMS 56 
usage in CMS/DOS 57 
time information, displaying during EXEC 

processing 286 
TO, operand of SPOOL command 123 
TOP, token stacked when edit macro executed 

at top-of-file 299 
TOP: message 74 
tokens 108 

with multiple variable symbols 257 
TOP, subcommand, moving current line 

pointer to top-of-file 74 
top-of-file 

executing edit macros 299 
indication in a file being edited 74 
TRACE, command, usage 221 
tracing 

output, printing 222 
program execution 22 

controlling the trace 222 
tracks 

entering extent information in terms of 

202 
number per cylinder on disk devices 203 
TRANSFER command, moving reader files 124 
transferring 

control in an EXEC procedure 

&ERROR control statement 286 
using &GOTO control statement 264 
transient area 

CMS commands that execute in 65 
creating modules to execute in 245 
location in virtual storage 227 
restrictions on modules executing in 
245 
translate tables 

defining input and output characters for 

40 
using on display terminals 335 
translating, virtual storage to EBCDIC 223 
transporting, VSAM data sets 211 
TRDNC 

option of COPYFILE command, used to 

convert record formats 83 
subcommand, setting right margin for 
input with the editor 87 
truncating 

data while changing lines with the 

editor 87 
input data while using the editor 86 
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trailing blanks from fixed-length 

records 83 
words in an EXEC procedure 255 
truncation, settings used by the editor 87 
TSOMAC tJACLIB 148,176 
TXTLIB 

command 

OS linkage editor control statements 

supported 153 
usage 153 
files 

assigning entry point names 153 
manipulating 153 
filetype, usage in CMS 56 
members, assigning names for 153 
TYPE 

command, displaying CMS files 44 
subcommand 

effect on current line pointer 73 
using to restore screen display 332 



U 

unassigning logical unit assignments in 
CMS/DOS 165 

underscore 

characters in a file being edited 86 
using on OVEBLAY subcommand 78 

unique clusters, defining 210 

unit record, devices 121 

unresolved references, how the loader 
resolves 154 

UPDATE, filetype, usage in CMS 56 

updating, CMS file directories 64 

UPDLOG filetype, usage in CMS 56 

UPDTxxxx filetype, usage in CMS 56 

DPSI 

byte, setting in CMS/DOS 184 
operand, of CMS SET command, example 
184 

user catalog 
VSAM 205 

in CMS/DOS 197 

user file directory 64 

user program area 227 

executing programs and CMS commands 244 

userid 

for your virtual machine 15 

of CMS batch virtual machine 231 

specifying for output spool files 122 

user-written 

commands, creating 157 
edit macros 306 



variable symbols 
compound 257 

examples of substitution 256 
how scanned 256 
in an EXEC procedure 109 
comparing 113 
using as counters 266 
reading values from the terminal 271 
stacking in edit macros 298 



variable-length EXEC files, considerations 

for writing edit macros 301 
VARS operand of SREAD control statement 

271 
verification setting 

changing in an edit macro 301 
changing on a display terminal 332 
columns used by the editor 76 
VERIFY subcommand 

canceling editor displays 94 
how to use 76 
using in an edit macro 301 
verifying, execution of an edit macro 301 
virtual 

addresses 

for disks 22 
for tapes 126 

for unit record devices 121 
storage (see virtual storage) 
virtual disks (see also disks) 

definition 21 
Virtual Machine Facility/370 (VM/370) 
basic description 13 
command summaries 314 
components 13 
environments 27 
virtual machines 
definition 13 
size 227 
virtual storage 

addresses, calculating 216 

CMS utilization 228 

displaying 223 

examining in debug environment 216 

how CMS uses 227 

increasing the size 97 

overlaying during program execution 244 

specifying locations for program 

execution 244 
used by the editor, what to do when it 
is full 96 
VM READ status, on a display screen 326 
VM/370 (see Virtual Machine Facility/370 

(VM/370)) 
vm/370 online 15 
VSAM 

access method, CMS support 138 
catalogs 

deleting 211 
passwords 206 
passwords in CMS/DOS 198 
using in CMS/DOS 195 
clusters 

defining 210 
deleting 211 
unique 210 
data sets, manipulating with the AMSERV 

command 187 
files 

identifying multivolume 208 
identifying multivolume in CMS/DOS 

199 
relationship to CMS files 51 
input and output files 
defining 201 
defining in CMS/DOS 194 
master catalog 
defining 204 



Index 



389 



defining in CMS/DOS 195 

identifying 203 

identifying before executing programs 

188 
identifying in CMS/DOS 195 
multivolume extents 
specifying 207 
specifying in CMS/DOS 199 
option 

of DLBL command 202 
of DLBL command, in CMS/DOS 194 
programs, compiling and executing in CMS 

187 
user catalogs 
defining 205 
defining in CMS/DOS 196 
using in CMS 187 
VSAPL program, invoicing on a display 
terminal 336 



DEBUG subcommand, example 218 
EDIT subcommand, usage 95 



Y subcommand, usage 95 



ZAP filetype, usage in CMS 56 
zone setting 

columns used by the editor 76 
increasing 87 
ZONE subcommand 

setting truncation columns for CHANGE 

subcommand 87 
specifying columns for the editor to 
search 77 



wait bit, in program new PSW, modifying 

224 
HAITT macro, usage 251 

warning messages, controlling whether you 
receive them 36 
writing 

CMS files 

in an EXEC procedure 282 
with the FSWBITE macro 248 
CMS files onto disk 

disk determination 61 
how the editor selects a disk 71 
edit macros 297 

error messages in an EXEC procedure 292 
labels on CMS disks 22 
lines to the terminal 251 
specific records in a CMS file 248 
tape marks, examples 128 
WRTERM macro, examples 251 



1 

19E virtual disk address, accessed as 
Y-disk 59 

190 virtual disk address 
accessed as S-disk 59 
using to IPL CMS 16 

191 virtual disk address, accessed as 
A-disk 59 

192 virtual disk address, accessed as 
D-disk 59 



3270 terminals (see display terminals) 
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